tmapper-py 0.1.0__py3-none-any.whl

tmapper/modularity.py

@@ -0,0 +1,74 @@
+"""Port of tmapper_tools/Qasym.m and calMod.m from the MATLAB toolbox."""
+
+import numpy as np
+
+
+def qasym(A, C):
+    """Modularity measure of an asymmetric, weighted network.
+
+    Port of MATLAB's ``Qasym.m``. Adapted from the canonical modularity
+    definition (Fortunato 2010, Physics Reports) for asymmetric networks
+    with weighted edges.
+
+    Parameters
+    ----------
+    A : array_like, shape (N, N)
+        Adjacency matrix, which may or may not be symmetric.
+    C : array_like, shape (N,)
+        Community assignment of each node.
+
+    Returns
+    -------
+    float
+        Modularity Q. Returns 0 for a zero-edge network (neither modular
+        nor non-modular).
+    """
+    A = np.asarray(A, dtype=float)
+    N_edges = A.sum()  # "2m" in other notations
+
+    if N_edges == 0:
+        return 0.0
+
+    k_source = A.sum(axis=1, keepdims=True)  # source degree
+    k_sink = A.sum(axis=0, keepdims=True)  # sink degree
+    P_ij = k_source @ k_sink / N_edges  # null model
+
+    C = np.asarray(C).ravel()
+    same_community = C[:, None] == C[None, :]
+
+    return float(np.sum((A - P_ij) * same_community) / N_edges)
+
+
+def cal_mod(W, m0):
+    """Modularity score of a (typically symmetric) network given a
+    community assignment.
+
+    Port of MATLAB's ``calMod.m``.
+
+    Parameters
+    ----------
+    W : array_like, shape (N, N)
+        Graph adjacency matrix.
+    m0 : array_like, shape (N,)
+        Categorical node labels / community assignment.
+
+    Returns
+    -------
+    float
+        Modularity score. Returns 0 for a zero-edge network (neither
+        modular nor non-modular).
+    """
+    W = np.asarray(W, dtype=float)
+    s = W.sum()  # sum of degrees of nodes (assuming symmetric)
+
+    if s == 0:
+        return 0.0
+
+    gamma = 1  # scaling parameter
+    B = (W - gamma * (W.sum(axis=1, keepdims=True) @ W.sum(axis=0, keepdims=True)) / s) / s
+    B = (B + B.T) / 2  # symmetrize
+
+    m0 = np.asarray(m0).ravel()
+    same_community = m0[:, None] == m0[None, :]
+
+    return float(B[same_community].sum())

tmapper/path_traffic.py

@@ -0,0 +1,35 @@
+"""Port of tmapper_tools/pathtraffic.m from the MATLAB toolbox."""
+
+import numpy as np
+
+
+def path_traffic(allpath, nodesize):
+    """Compute traffic statistics (based on node size) along each path.
+
+    Port of MATLAB's ``pathtraffic.m``. Note: matches MATLAB's ``std()``
+    convention of dividing by ``N-1`` (sample standard deviation), not
+    numpy's default ``N``.
+
+    Parameters
+    ----------
+    allpath : sequence of sequence of int
+        Each element is a path of node indices.
+    nodesize : array_like
+        Size of each node, indexed the same way as the indices in
+        ``allpath``.
+
+    Returns
+    -------
+    traf_mean, traf_med, traf_min, traf_max, traf_std : numpy.ndarray
+        One value per path in ``allpath``.
+    """
+    nodesize = np.asarray(nodesize, dtype=float)
+    path_nodesize = [nodesize[np.asarray(p, dtype=int)] for p in allpath]
+
+    traf_mean = np.array([p.mean() for p in path_nodesize])
+    traf_med = np.array([np.median(p) for p in path_nodesize])
+    traf_min = np.array([p.min() for p in path_nodesize])
+    traf_max = np.array([p.max() for p in path_nodesize])
+    traf_std = np.array([p.std(ddof=1) if len(p) > 1 else 0.0 for p in path_nodesize])
+
+    return traf_mean, traf_med, traf_min, traf_max, traf_std

tmapper/plotting.py

@@ -0,0 +1,463 @@
+"""Port of tmapper_tools/plottmgraph.m and plotgraphtcm.m from the MATLAB
+toolbox."""
+
+import numpy as np
+import networkx as nx
+from scipy import stats
+
+from .labeling import find_node_label
+from .tcm_distance import tcm_distance
+from ._shortest_path import all_pairs_distance
+
+
+def _rescale(x, lo, hi):
+    """Linearly map x's [min, max] to [lo, hi], matching MATLAB's rescale."""
+    x = np.asarray(x, dtype=float)
+    xmin, xmax = x.min(), x.max()
+    return lo + (x - xmin) / (xmax - xmin) * (hi - lo)
+
+
+def _normalize_positions(pos):
+    """Rescale a layout so the farthest node sits at radius 1."""
+    pts = np.array(list(pos.values()))
+    max_r = np.max(np.linalg.norm(pts, axis=1))
+    scale = 1.0 / max_r if max_r > 0 else 1.0
+    return {n: xy * scale for n, xy in pos.items()}
+
+
+def _expand_center(pos, gamma):
+    """Log-radial de-clumping: remap each node's radius r -> log1p(gamma*r).
+
+    Force-directed layouts (spring/ForceAtlas2) tend to pack the bulk of
+    nodes into a dense central clump with only a few outliers stretching
+    the frame. Since log1p(gamma*r)/r is largest at small r and flattens
+    out at large r, this pushes the dense core outward proportionally
+    more than the already-spread-out periphery, without disturbing
+    angular position or relative radial order.
+    """
+    out = {}
+    for n, xy in pos.items():
+        r = np.linalg.norm(xy)
+        if r > 0:
+            rn = np.log1p(gamma * r)
+            out[n] = xy * (rn / r)
+        else:
+            out[n] = xy
+    return out
+
+
+def _prepare_node_size(nodemembers, nodesizerange, nodesizemode):
+    """Shared node-size computation for :func:`plot_tmgraph` and
+    :func:`plot_tmgraph_interactive`: member count -> optional
+    rank/log transform -> rescaled to ``nodesizerange``."""
+    n_nodes = len(nodemembers)
+    nodesize = np.array([len(m) for m in nodemembers], dtype=float)
+    buniform = len(set(nodesize.tolist())) == 1
+    if not buniform:
+        if nodesizemode == "rank":
+            nodesize = stats.rankdata(nodesize, method="average")
+        elif nodesizemode == "log":
+            nodesize = np.log10(nodesize)
+        # 'original' (or anything else): leave nodesize as-is, matching
+        # MATLAB's switch with no matching/default case
+        nodesize = _rescale(nodesize, nodesizerange[0], nodesizerange[1])
+    else:
+        span = nodesizerange[1] - nodesizerange[0]
+        nodesize = np.full(n_nodes, nodesizerange[0] + span / n_nodes)
+    return nodesize
+
+
+def _compute_layout(g, nodelist, center_expand):
+    """Shared layout computation for :func:`plot_tmgraph` and
+    :func:`plot_tmgraph_interactive`: igraph's DrL layout (falls back to
+    spring_layout for the trivial 1-node case), normalized to the unit
+    circle and optionally de-clumped. See :func:`_expand_center`."""
+    n_nodes = len(nodelist)
+    if n_nodes > 1:
+        import igraph as ig
+
+        idx_of = {node: i for i, node in enumerate(nodelist)}
+        edges = [(idx_of[u], idx_of[v]) for u, v in g.edges()]
+        g_ig = ig.Graph(n=n_nodes, edges=edges, directed=g.is_directed())
+        coords = np.array(g_ig.layout_drl().coords)
+        pos = {nodelist[i]: coords[i] for i in range(n_nodes)}
+    else:
+        pos = nx.spring_layout(g, weight=None, seed=0)
+
+    pos = _normalize_positions(pos)
+    if center_expand:
+        pos = _expand_center(pos, center_expand)
+    return pos
+
+
+def plot_tmgraph(
+    g,
+    x_label=None,
+    nodemembers=None,
+    *,
+    ax=None,
+    nodesizerange=(1, 10),
+    nodesizemode="log",
+    colorlabel="x_label",
+    cmap="jet",
+    labelmethod="mode",
+    nodeclim=None,
+    nodescatter=False,
+    center_expand=4.0,
+):
+    """Plot a temporal mapper graph (without a recurrence plot).
+
+    Port of MATLAB's ``plottmgraph.m``.
+
+    Parameters
+    ----------
+    g : networkx.Graph or networkx.DiGraph
+        The graph to plot.
+    x_label : array_like, optional
+        A label for each member of each node, indexed the same way as the
+        indices inside ``nodemembers``. Defaults to a constant array of
+        ones sized to the number of unique members across all nodes.
+    nodemembers : sequence of sequence of int, optional
+        ``nodemembers[n]`` gives the indices belonging to node n. Defaults
+        to one singleton member per node (0..N-1).
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into. A new figure/axes is created if not given.
+    nodesizerange : (float, float), default (1, 10)
+        (min, max) marker size.
+    nodesizemode : {'log', 'rank', 'original'}, default 'log'
+        How to transform node sizes before rescaling to ``nodesizerange``.
+    colorlabel : str, default 'x_label'
+        Colorbar label.
+    cmap : str or matplotlib.colors.Colormap, default 'jet'
+        Colormap for node coloring.
+    labelmethod : {'mode', 'mean', 'median', 'none'} or callable, default 'mode'
+        See :func:`tmapper.labeling.find_node_label`.
+    nodeclim : (float, float), optional
+        Color axis limits. Defaults to (min(x_label), max(x_label)).
+    nodescatter : bool, default False
+        Whether to overlay a scatter plot on top of the graph nodes.
+    center_expand : float, default 4.0
+        Log-radial de-clumping strength applied to the layout after
+        normalizing it to the unit circle (0 disables it). Force-directed
+        layouts tend to pack most nodes into a dense central clump with a
+        few outliers stretching the frame; this spreads the dense core
+        outward without disturbing the outer structure. See
+        :func:`_expand_center`.
+
+    Returns
+    -------
+    ax : matplotlib.axes.Axes
+    cbar : matplotlib.colorbar.Colorbar
+    node_collection : matplotlib.collections.PathCollection
+        The drawn graph nodes.
+    scatter_collection : matplotlib.collections.PathCollection or None
+        The scatter overlay, if ``nodescatter`` is True.
+    """
+    import matplotlib.pyplot as plt
+
+    nodelist = list(g.nodes())
+    n_nodes = len(nodelist)
+
+    if nodemembers is None:
+        nodemembers = [[i] for i in range(n_nodes)]
+
+    if x_label is None:
+        all_members = sorted({m for members in nodemembers for m in members})
+        x_label = np.ones(len(all_members))
+    x_label = np.asarray(x_label, dtype=float)
+
+    if nodeclim is None:
+        nodeclim = (float(np.min(x_label)), float(np.max(x_label)))
+
+    # -- define node size and labels/colors
+    nodesize = _prepare_node_size(nodemembers, nodesizerange, nodesizemode)
+    nodelabel = find_node_label(nodemembers, x_label, labelmethod=labelmethod)
+
+    # -- plotting
+    if ax is None:
+        _, ax = plt.subplots()
+
+    pos = _compute_layout(g, nodelist, center_expand)
+
+    xs = np.array([pos[n][0] for n in nodelist])
+    ys = np.array([pos[n][1] for n in nodelist])
+
+    # Edges visible but behind (zorder=1); nodes outlined and drawn in
+    # front (zorder=3), smallest last, so small nodes aren't buried
+    # under large ones and stay crisp regardless of edge clutter.
+    edge_collection = nx.draw_networkx_edges(
+        g, pos, ax=ax, alpha=0.6, edge_color="#888888", width=0.8,
+        arrowsize=6, nodelist=nodelist,
+    )
+    for obj in (edge_collection if isinstance(edge_collection, list) else [edge_collection]):
+        if obj is not None:
+            obj.set_zorder(1)
+
+    order = np.argsort(nodesize, kind="stable")[::-1]  # largest first, smallest drawn last (on top)
+    node_collection = ax.scatter(
+        xs[order], ys[order], s=(nodesize[order] ** 2), c=nodelabel[order], cmap=cmap,
+        vmin=nodeclim[0] if nodeclim[1] != nodeclim[0] else None,
+        vmax=nodeclim[1] if nodeclim[1] != nodeclim[0] else None,
+        edgecolors="black", linewidths=0.5, zorder=3,
+    )
+    ax.set_aspect("equal")
+    ax.axis("off")
+
+    sm = plt.cm.ScalarMappable(cmap=cmap)
+    sm.set_array(nodelabel)
+    if nodeclim[1] != nodeclim[0]:
+        sm.set_clim(nodeclim[0], nodeclim[1])
+    cbar = plt.colorbar(sm, ax=ax)
+    cbar.set_label(colorlabel)
+
+    scatter_collection = None
+    if nodescatter:
+        order = np.argsort(nodesize, kind="stable")
+        scatter_collection = ax.scatter(
+            xs[order], ys[order], s=(nodesize[order] ** 2),
+            c=nodelabel[order], cmap=cmap,
+            vmin=nodeclim[0] if nodeclim[1] != nodeclim[0] else None,
+            vmax=nodeclim[1] if nodeclim[1] != nodeclim[0] else None,
+            edgecolors="k", linewidths=0.2,
+        )
+
+    return ax, cbar, node_collection, scatter_collection
+
+
+def plot_tmgraph_interactive(
+    g,
+    x_label=None,
+    nodemembers=None,
+    *,
+    nodesizerange=(6, 40),
+    nodesizemode="log",
+    colorlabel="x_label",
+    cmap="jet",
+    labelmethod="mode",
+    nodeclim=None,
+    center_expand=4.0,
+    title="",
+    output_path=None,
+):
+    """Plot a temporal mapper graph as a draggable/zoomable/hoverable
+    standalone HTML page (via pyvis/vis.js), instead of a static image.
+
+    Uses the same layout, node-size, and coloring logic as
+    :func:`plot_tmgraph` (so the two should look like the same network),
+    with physics disabled -- nodes stay exactly where the layout put
+    them, but can still be dragged, and hovering shows each node's size
+    and color-label value.
+
+    Parameters
+    ----------
+    g : networkx.Graph or networkx.DiGraph
+        The graph to plot.
+    x_label : array_like, optional
+        See :func:`plot_tmgraph`.
+    nodemembers : sequence of sequence of int, optional
+        See :func:`plot_tmgraph`.
+    nodesizerange : (float, float), default (6, 40)
+        (min, max) node radius in pixels (pyvis/vis.js sizes nodes by
+        radius, unlike matplotlib's area-based marker size -- so this
+        default is not directly comparable to :func:`plot_tmgraph`'s).
+    nodesizemode : {'log', 'rank', 'original'}, default 'log'
+        See :func:`plot_tmgraph`.
+    colorlabel : str, default 'x_label'
+        Legend label (rendered as a small embedded colorbar image).
+    cmap : str or matplotlib.colors.Colormap, default 'jet'
+        Colormap for node coloring -- anything matplotlib accepts,
+        including a discrete :class:`~matplotlib.colors.ListedColormap`
+        for categorical labels.
+    labelmethod : {'mode', 'mean', 'median', 'none'} or callable, default 'mode'
+        See :func:`tmapper.labeling.find_node_label`.
+    nodeclim : (float, float), optional
+        Color axis limits. Defaults to (min(x_label), max(x_label)).
+    center_expand : float, default 4.0
+        See :func:`plot_tmgraph`.
+    title : str, default ''
+        Page heading (e.g. summarize the construction parameters here).
+    output_path : str, optional
+        If given, also write the standalone HTML page to this path.
+        Default None -- no file is written; use the returned ``html``
+        string instead (e.g. pass it directly to
+        ``streamlit.components.v1.html(html, height=900)`` rather than
+        writing to disk and reading it back).
+
+    Returns
+    -------
+    net : pyvis.network.Network
+        The populated network.
+    html : str
+        The standalone HTML page as a string (already includes the
+        embedded colorbar legend) -- identical to what gets written to
+        ``output_path`` when one is given.
+    """
+    import base64
+    from io import BytesIO
+
+    import matplotlib.pyplot as plt
+    import matplotlib.colors as mcolors
+    from pyvis.network import Network
+
+    nodelist = list(g.nodes())
+    n_nodes = len(nodelist)
+
+    if nodemembers is None:
+        nodemembers = [[i] for i in range(n_nodes)]
+
+    if x_label is None:
+        all_members = sorted({m for members in nodemembers for m in members})
+        x_label = np.ones(len(all_members))
+    x_label = np.asarray(x_label, dtype=float)
+
+    if nodeclim is None:
+        nodeclim = (float(np.min(x_label)), float(np.max(x_label)))
+
+    nodesize = _prepare_node_size(nodemembers, nodesizerange, nodesizemode)
+    nodelabel = find_node_label(nodemembers, x_label, labelmethod=labelmethod)
+    pos = _compute_layout(g, nodelist, center_expand)
+
+    # -- per-node hex colors via matplotlib's colormap machinery, so this
+    # accepts the exact same `cmap`/`nodeclim` (continuous or discrete)
+    # as plot_tmgraph.
+    cmap_obj = plt.get_cmap(cmap) if isinstance(cmap, str) else cmap
+    vmin, vmax = nodeclim if nodeclim[1] != nodeclim[0] else (nodeclim[0] - 0.5, nodeclim[0] + 0.5)
+    norm = mcolors.Normalize(vmin=vmin, vmax=vmax)
+    node_colors_hex = [mcolors.to_hex(cmap_obj(norm(v))) for v in nodelabel]
+
+    net = Network(
+        height="900px", width="100%", directed=g.is_directed(), bgcolor="#ffffff",
+        cdn_resources="in_line", notebook=False, heading=title,
+    )
+    net.set_options('{"physics": {"enabled": false}}')
+
+    SCALE = 800  # pyvis coordinates are pixels; our layout is normalized to roughly [-1.x, 1.x]
+    order = np.argsort(nodesize, kind="stable")[::-1]  # largest first, smallest added last (drawn on top)
+    for i in order:
+        i = int(i)
+        n = nodelist[i]
+        x, y = pos[n]
+        net.add_node(
+            i,
+            label="",
+            title=f"node {n} | members={int(len(nodemembers[i]))} | {colorlabel}={nodelabel[i]:.3g}",
+            x=float(x * SCALE), y=float(-y * SCALE),  # flip y: vis.js y-axis points down
+            size=float(nodesize[i]), color=node_colors_hex[i], physics=False,
+        )
+    idx_of = {n: i for i, n in enumerate(nodelist)}
+    edge_kwargs = {"arrows": "to"} if g.is_directed() else {}
+    for u, v in g.edges():
+        net.add_edge(idx_of[u], idx_of[v], color="#bbbbbb", width=1, **edge_kwargs)
+
+    html = net.generate_html(notebook=False)
+
+    # pyvis's own template renders "<h1>{{heading}}</h1>" twice
+    # unconditionally -- drop the second copy.
+    if title:
+        heading_block = f"<h1>{title}</h1>"
+        first = html.find(heading_block)
+        second = html.find(heading_block, first + 1)
+        if second != -1:
+            html = html[:second] + html[second + len(heading_block):]
+
+    # -- embed a small matplotlib colorbar as the legend, reusing the
+    # exact cmap/norm above so it always matches the node colors.
+    fig_cb, ax_cb = plt.subplots(figsize=(4, 0.5))
+    cbar = fig_cb.colorbar(
+        plt.cm.ScalarMappable(cmap=cmap_obj, norm=norm), cax=ax_cb, orientation="horizontal"
+    )
+    cbar.set_label(colorlabel)
+    buf = BytesIO()
+    fig_cb.savefig(buf, format="png", dpi=130, bbox_inches="tight", transparent=True)
+    plt.close(fig_cb)
+    legend_b64 = base64.b64encode(buf.getvalue()).decode("ascii")
+    legend_html = (
+        f'<div style="text-align:center;">'
+        f'<img src="data:image/png;base64,{legend_b64}"></div>'
+    )
+    anchor = "</h1>" if title else "<body>"
+    html = html.replace(anchor, anchor + "\n" + legend_html, 1)
+
+    if output_path is not None:
+        with open(output_path, "w", encoding="utf-8") as f:
+            f.write(html)
+
+    return net, html
+
+
+def plot_tmgraph_tcm(g, x_label, t, nodemembers, **kwargs):
+    """Plot a temporal mapper graph alongside its geodesic recurrence plot.
+
+    Port of MATLAB's ``plotgraphtcm.m``. Calls :func:`plot_tmgraph`
+    internally for the left subplot (all ``**kwargs`` are passed through),
+    so it accepts the same styling parameters.
+
+    Parameters
+    ----------
+    g : networkx.Graph or networkx.DiGraph
+        The (simplified) graph to plot.
+    x_label : array_like
+        A label for each time point in the time series.
+    t : array_like
+        Actual time (or a time index) associated with each time point,
+        used as the recurrence plot's axis labels.
+    nodemembers : sequence of sequence of int
+        ``nodemembers[n]`` gives the original time-point indices
+        belonging to node n.
+    **kwargs
+        Passed through to :func:`plot_tmgraph`.
+
+    Returns
+    -------
+    ax1, ax2 : matplotlib.axes.Axes
+        The network plot and recurrence plot axes.
+    cbar, cbar2 : matplotlib.colorbar.Colorbar
+    node_collection, scatter_collection
+        As returned by :func:`plot_tmgraph`.
+    D_geo : numpy.ndarray
+        The recurrence plot matrix.
+    """
+    import matplotlib.pyplot as plt
+    import matplotlib.dates as mdates
+
+    nodesize = np.array([len(m) for m in nodemembers])
+    bsinglemember = np.all(nodesize == 1)
+
+    # constrained_layout resolves spacing between subplots/colorbars
+    # automatically, avoiding overlap between cbar's label and ax2's ylabel.
+    fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(11, 4.5), constrained_layout=True)
+
+    ax1, cbar, node_collection, scatter_collection = plot_tmgraph(
+        g, x_label, nodemembers, ax=ax1, **kwargs
+    )
+
+    if bsinglemember:
+        D_geo = all_pairs_distance(g, list(g.nodes()), weight=None)
+    else:
+        D_geo = tcm_distance(g, nodemembers)
+
+    t = np.asarray(t)
+    is_datetime = np.issubdtype(t.dtype, np.datetime64)
+    t_num = mdates.date2num(t) if is_datetime else t.astype(float)
+
+    im = ax2.imshow(
+        D_geo, cmap="hot",
+        extent=[t_num.min(), t_num.max(), t_num.max(), t_num.min()],
+        aspect="equal", interpolation="nearest",  # matches MATLAB's imagesc (flat, unsmoothed cells)
+    )
+    cbar2 = plt.colorbar(im, ax=ax2)
+    cbar2.set_label("path length")
+
+    if is_datetime:
+        for axis in (ax2.xaxis, ax2.yaxis):
+            locator = mdates.AutoDateLocator()
+            axis.set_major_locator(locator)
+            axis.set_major_formatter(mdates.ConciseDateFormatter(locator))
+        ax2.set_xlabel("time")
+        ax2.set_ylabel("time")
+    else:
+        ax2.set_xlabel("time (s)")
+        ax2.set_ylabel("time (s)")
+    ax2.set_title("geodesic recurrence plot")
+
+    return ax1, ax2, cbar, cbar2, node_collection, scatter_collection, D_geo

tmapper/sample_data.py

@@ -0,0 +1,19 @@
+"""Locating the bundled sample dataset."""
+
+from pathlib import Path
+
+SAMPLE_DATA_FILE = "EL_temp.csv"
+
+
+def sample_data_path():
+    """Path to the bundled East Lansing daily weather CSV.
+
+    Ships inside the package, so this resolves the same way whether tmapper
+    was pip-installed or is being run from a clone -- code that hard-codes
+    ``"sampledata/EL_temp.csv"`` only works from the repository root.
+
+    Note this is the *full* historical record (57709 daily rows). Building a
+    network needs a slice of it: the pairwise distance matrix is O(N^2), so
+    the whole thing would ask for tens of GB. See the Quickstart.
+    """
+    return Path(__file__).resolve().parent / "sampledata" / SAMPLE_DATA_FILE