tmapper-py 0.1.0__py3-none-any.whl

tmapper/tcm_distance.py

@@ -0,0 +1,63 @@
+"""Port of tmapper_tools/TCMdistance.m from the MATLAB toolbox."""
+
+import numpy as np
+import networkx as nx
+
+from ._shortest_path import all_pairs_distance
+
+
+def tcm_distance(g, nodet, weighted=False):
+    """Compute a temporal connectivity matrix: for every pair of original
+    time points, the shortest path length between the nodes (of a
+    simplified graph ``g``) that contain them.
+
+    Port of MATLAB's ``TCMdistance.m``. Sizes its output by the full range
+    covered by ``nodet`` (``max - min + 1``), not just the count of
+    distinct points referenced -- so time points genuinely not covered by
+    any node in ``nodet`` correctly stay ``NaN`` rather than being silently
+    zero-filled.
+
+    Parameters
+    ----------
+    g : networkx.Graph or networkx.DiGraph
+        The simplified graph.
+    nodet : sequence of sequence of int
+        ``nodet[i]`` gives the original time-point indices belonging to
+        node i of ``g`` (in the same node order as ``g.nodes()``).
+    weighted : bool, default False
+        Whether to use ``g``'s edge weights. If False, every edge is
+        treated as weight 1 (hop count).
+
+    Returns
+    -------
+    numpy.ndarray, shape (Nt, Nt)
+        The temporal connectivity matrix, where Nt = max(nodet) - min(nodet) + 1.
+        Entries for time points never covered by any node stay NaN.
+    """
+    nodelist = list(g.nodes())
+    all_t = np.concatenate([np.asarray(list(nt), dtype=int) for nt in nodet]) if nodet else np.array([], dtype=int)
+    if all_t.size == 0:
+        return np.zeros((0, 0))
+    t_0 = all_t.min()
+    Nt = all_t.max() - t_0 + 1
+
+    distmat = all_pairs_distance(g, nodelist, weight="weight" if weighted else None)
+
+    tcm = np.full((Nt, Nt), np.nan)
+
+    n_nodes = len(nodelist)
+    idx_lists = [np.asarray(list(nt), dtype=int) - t_0 for nt in nodet]
+
+    for i in range(n_nodes):
+        ii = idx_lists[i]
+        tcm[np.ix_(ii, ii)] = 0
+
+    for i in range(n_nodes):
+        for j in range(i + 1, n_nodes):
+            ii, jj = idx_lists[i], idx_lists[j]
+            block_ij = tcm[np.ix_(ii, jj)]
+            tcm[np.ix_(ii, jj)] = np.fmin(block_ij, distmat[i, j])
+            block_ji = tcm[np.ix_(jj, ii)]
+            tcm[np.ix_(jj, ii)] = np.fmin(block_ji, distmat[j, i])
+
+    return tcm

tmapper/tknndigraph.py

@@ -0,0 +1,190 @@
+"""Port of tmapper_tools/tknndigraph.m from the MATLAB toolbox."""
+
+import numpy as np
+import networkx as nx
+from scipy.spatial.distance import cdist
+
+
+def _percentile_with_inf(values, prct):
+    """Like ``np.percentile`` (linear interpolation method), but robust to
+    ``inf`` entries. ``np.percentile`` can return NaN when the interpolation
+    boundary falls between two ``inf`` values, because its formula computes
+    ``a + weight * (b - a)`` and ``inf - inf`` is NaN even when ``weight``
+    is (mathematically) zero -- 0 * NaN is still NaN, not 0. This matters
+    here since D routinely contains inf entries (masked self-loops/temporal
+    exclusions) and MATLAB's prctile does not have this problem.
+    """
+    sorted_vals = np.sort(np.asarray(values).ravel())
+    n = sorted_vals.size
+    if n == 0:
+        return np.inf
+    virtual_idx = (prct / 100.0) * (n - 1)
+    lo = int(np.floor(virtual_idx))
+    hi = int(np.ceil(virtual_idx))
+    if lo == hi:
+        return sorted_vals[lo]
+    a, b = sorted_vals[lo], sorted_vals[hi]
+    if np.isinf(a) and np.isinf(b) and a == b:
+        return a
+    frac = virtual_idx - lo
+    return a + frac * (b - a)
+
+
+def tknndigraph(
+    X_or_D,
+    k,
+    tidx,
+    *,
+    reciprocal=True,
+    time_exclude_space=True,
+    time_exclude_range=1,
+    max_neighbor_dist=np.inf,
+    max_neighbor_dist_prct=100.0,
+):
+    """Construct a directed graph based on k-nearest neighbors that also
+    includes temporal neighbors (t -> t+1 links).
+
+    Port of MATLAB's ``tknndigraph.m``. Node i of the returned graph
+    corresponds to row i of ``X_or_D`` / element i of ``tidx`` (0-indexed,
+    unlike the 1-indexed MATLAB original).
+
+    Parameters
+    ----------
+    X_or_D : array_like, shape (N, d) or (N, N)
+        Either raw coordinates (N points in d-dim space) or a precomputed
+        (N, N) distance matrix. Auto-detected: treated as a distance
+        matrix only if square *and* symmetric; otherwise treated as raw
+        coordinates and converted to a Euclidean distance matrix.
+    k : int
+        Max number of spatial neighbors per point. Must be a positive
+        integer strictly less than N.
+    tidx : array_like of int, shape (N,)
+        Time index per point. Two points x, y are temporal neighbors iff
+        ``tidx[y] == tidx[x] + 1``.
+    reciprocal : bool, default True
+        Whether to require spatial k-NN links to be mutual (both
+        directions) to be kept.
+    time_exclude_space : bool, default True
+        Whether temporal neighbors are barred from also counting as
+        spatial neighbors.
+    time_exclude_range : int, default 1
+        How many following time points are excluded from spatial-kNN
+        consideration.
+    max_neighbor_dist : float, default inf
+        Absolute distance cutoff for spatial neighbors.
+    max_neighbor_dist_prct : float, default 100
+        Percentile distance cutoff for spatial neighbors. The stricter
+        (smaller) of this and ``max_neighbor_dist`` is applied.
+
+    Returns
+    -------
+    g : networkx.DiGraph
+        Unweighted directed graph, one node per input point.
+    par : dict
+        Parameters actually used, including the resolved
+        ``max_neighbor_dist``.
+    """
+    X_or_D = np.asarray(X_or_D, dtype=float)
+    if X_or_D.ndim != 2:
+        raise ValueError("X_or_D must be a 2D array.")
+    if not (np.isscalar(k) and float(k) == round(float(k)) and k >= 1):
+        raise ValueError("k must be a positive integer scalar.")
+    k = int(k)
+
+    tidx = np.asarray(tidx, dtype=float).ravel()
+    if tidx.shape[0] != X_or_D.shape[0]:
+        raise ValueError(
+            "tidx must have the same number of elements as rows of X_or_D."
+        )
+
+    par = {
+        "reciprocal": reciprocal,
+        "time_exclude_space": time_exclude_space,
+        "time_exclude_range": time_exclude_range,
+        "max_neighbor_dist": max_neighbor_dist,
+        "max_neighbor_dist_prct": max_neighbor_dist_prct,
+        "k": k,
+    }
+
+    # -- check input and obtain distance matrix D
+    nr, nc = X_or_D.shape
+    if nr != nc or not np.allclose(X_or_D, X_or_D.T):
+        D = cdist(X_or_D, X_or_D)
+    else:
+        D = X_or_D.copy()
+    Nn = D.shape[0]
+
+    if k >= Nn:
+        raise ValueError(f"k must be smaller than the number of points ({Nn}).")
+
+    np.fill_diagonal(D, np.inf)  # exclude self-loops
+
+    # -- find indices for temporal links D[i(t), i(t+1)]
+    # t_wafter[i] is True iff point i has a point immediately after it in time
+    # (mirrors MATLAB's circshift(tidx,-1,1) - 1 == tidx, including its
+    # wraparound behavior at the last index, which is virtually always False
+    # for non-cyclic tidx and is harmless here for the same reason it is in
+    # the original).
+    tidx_next = np.roll(tidx, -1)
+    t_wafter = tidx_next - 1 == tidx
+
+    # t_after_idx1: unconditional immediate temporal edges i -> i+1
+    t_after_idx1 = np.zeros((Nn, Nn), dtype=bool)
+    for i in range(Nn):
+        if t_wafter[i]:
+            t_after_idx1[i, (i + 1) % Nn] = True
+
+    # t_after_idx: temporal-exclusion mask, extended up to time_exclude_range
+    # steps, restricted to strictly-forward (i < j) positions
+    t_after_idx = np.zeros((Nn, Nn), dtype=bool)
+    for n in range(1, time_exclude_range + 1):
+        for i in range(Nn):
+            if t_wafter[i]:
+                t_after_idx[i, (i + n) % Nn] = True
+    upper = np.triu(np.ones((Nn, Nn), dtype=bool), k=1)
+    t_after_idx = t_after_idx & upper
+
+    if time_exclude_space:
+        D[t_after_idx] = np.inf
+
+    # -- compute adjacency matrix (k nearest neighbors per row)
+    order = np.argsort(D, axis=1, kind="stable")
+    D_sorted = np.take_along_axis(D, order, axis=1)
+    A = np.zeros((Nn, Nn), dtype=bool)
+    rows = np.repeat(np.arange(Nn), k)
+    cols = order[:, :k].ravel()
+    A[rows, cols] = True
+
+    # -- check for duplicate points: any other point tied with the k-th
+    # nearest neighbor's distance is also included
+    dmax = D_sorted[:, k - 1][:, None]
+    A |= D <= dmax
+
+    # -- get distance threshold (the stricter of the absolute and percentile caps).
+    # NOTE: matches MATLAB's prctile(D(:), Prct) exactly by computing the
+    # percentile over the *full* D, Inf entries included (the masked
+    # diagonal/temporal-exclusion entries) -- not just the finite values.
+    prct_dist = _percentile_with_inf(D, max_neighbor_dist_prct)
+    resolved_max_dist = min(prct_dist, max_neighbor_dist)
+    par["max_neighbor_dist"] = resolved_max_dist
+
+    # -- remove neighbors that exceed max distance
+    A[D > resolved_max_dist] = False
+
+    # -- exclude or retain temporal links as spatial links
+    if time_exclude_space:
+        A_space = A & ~t_after_idx
+    else:
+        A_space = A.copy()
+
+    # -- enforce symmetry of spatial links
+    if reciprocal:
+        A_space = A_space & A_space.T
+    else:
+        A_space = A_space | A_space.T
+
+    # -- (re-)incorporate temporal links
+    A_final = t_after_idx1 | A_space
+
+    g = nx.from_numpy_array(A_final, create_using=nx.DiGraph)
+    return g, par

tmapper_py-0.1.0.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: tmapper-py
+Version: 0.1.0
+Summary: Python port of Temporal Mapper 2 -- build attractor transition networks from time-series data
+Author: Mengsen Zhang
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/Multiscale-Complex-Systems-Lab/tmapper-py
+Project-URL: MATLAB original, https://github.com/Multiscale-Complex-Systems-Lab/tmapper2
+Keywords: temporal mapper,topological data analysis,mapper,dynamical systems,time series,attractor,recurrence
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: networkx>=3.0
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == "plot"
+Requires-Dist: python-igraph>=1.0; extra == "plot"
+Requires-Dist: pyvis>=0.3; extra == "plot"
+Provides-Extra: app
+Requires-Dist: streamlit>=1.30; extra == "app"
+Requires-Dist: pandas>=1.5; extra == "app"
+Requires-Dist: matplotlib>=3.7; extra == "app"
+Requires-Dist: python-igraph>=1.0; extra == "app"
+Requires-Dist: pyvis>=0.3; extra == "app"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pandas>=1.5; extra == "test"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
+Dynamic: license-file
+
+# tmapper (Python)
+
+A Python port of [Temporal Mapper 2](https://github.com/Multiscale-Complex-Systems-Lab/tmapper2), a toolbox for building **attractor transition networks** from time-series data.
+
+**Status: feature-complete port.** Both the core two-step pipeline (`tknndigraph` + `filtergraph` + plotting) and the secondary cycle/path analysis toolkit (cycle counting/clustering, path decomposition, traffic, modularity) are ported and tested. `tknngraph.m` (a legacy, unused MATLAB function) was intentionally not ported.
+
+For the full background, citation, and the original MATLAB implementation, see [tmapper2](https://github.com/Multiscale-Complex-Systems-Lab/tmapper2).
+
+**Documentation, quickstart, and full API reference:** https://multiscale-complex-systems-lab.github.io/tmapper-py/
+
+## What's included
+
+- **Core pipeline**: `tknndigraph`, `filtergraph`, `find_node_label`, `tcm_distance`, `plot_tmgraph`, `plot_tmgraph_tcm`, `plot_tmgraph_interactive` (draggable/zoomable/hoverable HTML via pyvis, no MATLAB equivalent)
+- **Standalone graph builders**: `knngraph`, `cknngraph`
+- **Graph/data utilities**: `node_size`, `node_measure`, `normalize_geodesic`, `normalize_tcm`, `members_to_tidx`, `subgraph_from_members`, `sym_dyn_to_digraph`, `digraph_to_graph`, `find_blocks`
+- **Cycle/path analysis toolkit**: `cycle_count` (Giscard/Kriege/Wilson combinatorial-sieve counter, third-party algorithm carrying its own BSD license -- see `cycle_count.py`), `cycle_count2p`, `reorg_cycles`, `cycle_path_overlap`, `cycle_cluster`, `cycle_cluster_conn`, `cycle_cutter`, `cycles_to_paths`, `cycle_path_decomp`, `path_traffic`, `qasym`, `cal_mod`
+- **Interactive app**: `tmapper-app`, a browser front end for the whole pipeline -- see below
+
+All ported functions were cross-checked node-for-node and edge-for-edge against real MATLAB output on deterministic test graphs (see the test suite for the same hand-derived oracle values used in the MATLAB toolbox's own `tests/`).
+
+## Installation
+
+```bash
+pip install tmapper-py                 # library
+pip install "tmapper-py[app]"          # library + the interactive app
+```
+
+(The distribution is `tmapper-py` -- `tmapper` alone isn't available on PyPI,
+see [Installation](https://multiscale-complex-systems-lab.github.io/tmapper-py/installation/).
+Everything imports as `import tmapper` either way.)
+
+For development, from a clone:
+
+```bash
+git clone https://github.com/Multiscale-Complex-Systems-Lab/tmapper-py.git
+cd tmapper-py
+pip install -e ".[app,test]"
+```
+
+## Interactive app
+
+Prefer point-and-click? `tmapper-app` runs the same pipeline in your browser -- load data, pick variables, turn the parameters, and explore the network without writing any code:
+
+```bash
+pip install "tmapper-py[app]"
+tmapper-app
+```
+
+It handles missing data and downsampling for you (dropping incomplete rows before an anti-aliasing lowpass), exports both figures and analysis-ready data (interactive HTML, PNGs, a per-timepoint `timeline.csv`, GraphML, and a provenance JSON), and shows a runnable script reproducing the current build.
+
+See the [Interactive App guide](https://multiscale-complex-systems-lab.github.io/tmapper-py/app/) for a full walkthrough.
+
+## Running tests
+
+```bash
+pytest
+```
+
+## Notes for users porting workflows from MATLAB
+
+- Node labels are 0-indexed (Pythonic), unlike the MATLAB original's 1-indexed convention.
+- If you z-score your data before calling `tknndigraph` (as `tmapper_demo.m` does), note that MATLAB's `zscore` divides by the sample standard deviation (`N-1`), while `scipy.stats.zscore` defaults to the population standard deviation (`N`). Pass `ddof=1` to `scipy.stats.zscore` to match MATLAB's convention -- otherwise results can subtly diverge near k-NN/threshold boundaries. (Verified: with `ddof=1`, the Python and MATLAB pipelines produce identical output down to floating-point precision on the sample dataset.)
+
+## License
+
+BSD 3-Clause License -- see [LICENSE](LICENSE).

tmapper_py-0.1.0.dist-info/RECORD

@@ -0,0 +1,31 @@
+tmapper/__init__.py,sha256=-2Jqu7rvO_C-WX4zo0wfmEXZSOx2RSUpDnYy-dtJFa8,1676
+tmapper/_shortest_path.py,sha256=TRyUOHOuizrMYWnsoy_SVCU2aL4Q1hcp41EO1KiuhcU,1036
+tmapper/cknngraph.py,sha256=Wamujr4i6h7fiCvm23yPL9whXXs5FbFEMghXmdjjxp8,2412
+tmapper/cycle_cluster.py,sha256=5EbTgUKEXnVexRf5g9LK3uSSkJXxmRbN2MdfMPk8TrA,4089
+tmapper/cycle_cluster_conn.py,sha256=1yvj7ksr2OODQZaVTyZI5DO11mQ-1ahvPIcOtPCmw3I,4263
+tmapper/cycle_count.py,sha256=ZMs4pT7xZnmKmQpE-to9UL0NIiwam53j1I27935TlUI,5640
+tmapper/cycle_count2p.py,sha256=TujH-xuqt4NHu-p36x1BQUOP7VkUmsWTKb-38fXfWww,2570
+tmapper/cycle_cutter.py,sha256=AQtHRYTACyXK9muW_NINiH_CSIAia4MmvvSaB2KuVmg,1341
+tmapper/cycle_overlap.py,sha256=dVOB952P2CX5wadm0rKqR-Nvc5kNhxcDxqVMfCa2BEo,2180
+tmapper/cycle_path_decomp.py,sha256=QUYcOFZ3x-KOErxtn24dVhkR0NmkUteYvy6LGXZKU6A,4446
+tmapper/cycles_to_paths.py,sha256=VNj1ipbd6OSRv2GK1Y4kBE4fyMj1RU_qu39pESaNF0I,1072
+tmapper/filtergraph.py,sha256=L17Bp6OU3MdcFm6ObUP9E726sT8qZZ-2i9LdlCyM79Y,4408
+tmapper/graph_utils.py,sha256=KY5ULQdk_l1GHfU18ilwdhgDZZZN0Ce9qUpJ47qcGZ4,9294
+tmapper/knngraph.py,sha256=HxEyl2xU8LVg25i1jE0A3LFTSSUgF1OoyoTQRggqoo4,1941
+tmapper/labeling.py,sha256=f1dZr-9yZcYtga0ZGC0NypQ1KiSgJm6EXxEZ4oCsLAI,1696
+tmapper/modularity.py,sha256=HMlALb9QNXwpgPu4UYvF8KAdIvfnzIYj9Uscd4wWuFA,2029
+tmapper/path_traffic.py,sha256=KnVKwirP3hCZKxCKqnNeqN2w5L7qnU80ZeiBhRg_QUU,1262
+tmapper/plotting.py,sha256=e_wZ3xND_KLEMV9hP4uWHb_hJaGe6gHtGZyHrAu_uDU,17669
+tmapper/sample_data.py,sha256=ODY_TKb95N6Bagaw75YMPIwbFjD9GZA5-MXdkFN1WmQ,715
+tmapper/tcm_distance.py,sha256=yvp99IRaBzXy1v_7PFd2ZsuWBQhkkpHZdsn3Nzkad1Q,2268
+tmapper/tknndigraph.py,sha256=M3aASlUW3K3_rE5OsTJ2KfhQQ0vpGAvg0Xz8ph-D9vE,7020
+tmapper/app/__init__.py,sha256=5APA90YXLvorLyJayo6wQ2XsroXfbuQX-Q6B5EsoEBw,305
+tmapper/app/launcher.py,sha256=3JT3uw1AzL8Ob6tJ01ogDGUh5hUWUNWbCLko0mi2_zQ,1127
+tmapper/app/streamlit_app.py,sha256=9dSPvVjSi6xdOYXr1pOlGWJmUAOQWvYHM8nfldFYl5M,55962
+tmapper/sampledata/EL_temp.csv,sha256=x8d1psZtkBhCagScJ6tdXZn_RxNyku5For6vwo6j2mA,1605205
+tmapper_py-0.1.0.dist-info/licenses/LICENSE,sha256=PrN1LOSoJpxEvEWu6ZqsD_haOJDbD7oY-U23XdiAVw4,1517
+tmapper_py-0.1.0.dist-info/METADATA,sha256=pR7DSIcXc66jZj_mDdNXhdpxMxc10RpKUdD6FRZbrVI,5769
+tmapper_py-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+tmapper_py-0.1.0.dist-info/entry_points.txt,sha256=37FDwhSH65AcTarmiBtrHV1ftPXMLnKzE4V7HSamDmA,58
+tmapper_py-0.1.0.dist-info/top_level.txt,sha256=rCHRsCknm1Ae25rp11L0fu_mQP7qcF7hUhgOZtNW5PM,8
+tmapper_py-0.1.0.dist-info/RECORD,,

tmapper_py-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tmapper_py-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tmapper-app = tmapper.app.launcher:main

tmapper_py-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Multiscale Complex Systems Lab
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

tmapper_py-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tmapper