tmapper-py 0.1.0__tar.gz

tmapper_py-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,66 @@
+# 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/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# Distribution name on PyPI, not the importable module (that's still
+# `tmapper`, see [tool.setuptools.packages.find] below). Plain "tmapper" is
+# blocked there by PyPI's anti-typosquatting check: it's a 1-character edit
+# from the existing "mapper" package (a similarly-themed topological data
+# analysis tool), which is exactly the pattern that check exists to catch.
+name = "tmapper-py"
+version = "0.1.0"
+description = "Python port of Temporal Mapper 2 -- build attractor transition networks from time-series data"
+readme = "README.md"
+requires-python = ">=3.10"
+# SPDX string + license-files: the `{ file = ... }` table form is
+# deprecated and stops working on setuptools >= 77.
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [{ name = "Mengsen Zhang" }]
+keywords = [
+    "temporal mapper", "topological data analysis", "mapper",
+    "dynamical systems", "time series", "attractor", "recurrence",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+dependencies = [
+    "numpy>=1.24",
+    "scipy>=1.10",
+    "networkx>=3.0",
+]
+
+[project.optional-dependencies]
+plot = ["matplotlib>=3.7", "python-igraph>=1.0", "pyvis>=0.3"]
+# pandas is declared explicitly rather than leaned on as a streamlit
+# transitive dependency: the app imports it directly, so it is a real
+# requirement of ours. The core library stays pandas-free.
+app = [
+    "streamlit>=1.30",
+    "pandas>=1.5",
+    "matplotlib>=3.7",
+    "python-igraph>=1.0",
+    "pyvis>=0.3",
+]
+# the app tests drive the app, so they need its dependencies too
+test = ["pytest>=7.0", "pandas>=1.5"]
+docs = ["mkdocs-material>=9.5", "mkdocstrings[python]>=0.25"]
+
+[project.scripts]
+# `pip install "tmapper-py[app]"` then just `tmapper-app`
+tmapper-app = "tmapper.app.launcher:main"
+
+[project.urls]
+Homepage = "https://github.com/Multiscale-Complex-Systems-Lab/tmapper-py"
+"MATLAB original" = "https://github.com/Multiscale-Complex-Systems-Lab/tmapper2"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+# the bundled sample dataset, so the app's "Try sample data" button and the
+# Quickstart work from a pip install and not only from a clone
+tmapper = ["sampledata/*.csv"]

tmapper_py-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tmapper_py-0.1.0/src/tmapper/__init__.py

@@ -0,0 +1,63 @@
+from .sample_data import sample_data_path
+from .tknndigraph import tknndigraph
+from .filtergraph import filtergraph
+from .labeling import find_node_label
+from .tcm_distance import tcm_distance
+from .plotting import plot_tmgraph, plot_tmgraph_tcm, plot_tmgraph_interactive
+from .knngraph import knngraph
+from .cknngraph import cknngraph
+from .cycle_count import cycle_count
+from .cycle_count2p import cycle_count2p, reorg_cycles
+from .cycle_overlap import cycle_path_overlap
+from .cycle_cluster import cycle_cluster
+from .cycle_cluster_conn import cycle_cluster_conn
+from .cycle_cutter import cycle_cutter
+from .cycles_to_paths import cycles_to_paths
+from .cycle_path_decomp import cycle_path_decomp
+from .path_traffic import path_traffic
+from .modularity import qasym, cal_mod
+from .graph_utils import (
+    node_size,
+    node_measure,
+    normalize_geodesic,
+    normalize_tcm,
+    members_to_tidx,
+    subgraph_from_members,
+    sym_dyn_to_digraph,
+    digraph_to_graph,
+    find_blocks,
+)
+
+__all__ = [
+    "sample_data_path",
+    "tknndigraph",
+    "filtergraph",
+    "find_node_label",
+    "tcm_distance",
+    "plot_tmgraph",
+    "plot_tmgraph_tcm",
+    "plot_tmgraph_interactive",
+    "knngraph",
+    "cknngraph",
+    "cycle_count",
+    "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",
+    "node_size",
+    "node_measure",
+    "normalize_geodesic",
+    "normalize_tcm",
+    "members_to_tidx",
+    "subgraph_from_members",
+    "sym_dyn_to_digraph",
+    "digraph_to_graph",
+    "find_blocks",
+]

tmapper_py-0.1.0/src/tmapper/_shortest_path.py

@@ -0,0 +1,22 @@
+"""Shared all-pairs shortest-path helper.
+
+Uses scipy's compiled Dijkstra (via ``scipy.sparse.csgraph.shortest_path``)
+instead of networkx's ``floyd_warshall_numpy``. The latter is O(n^3) with
+substantial per-iteration numpy overhead and becomes the dominant cost at
+realistic graph sizes (a few thousand nodes); our graphs are sparse (a
+handful of edges per node from the k-NN construction), where Dijkstra from
+every source is asymptotically and practically much faster.
+"""
+
+import networkx as nx
+from scipy.sparse.csgraph import shortest_path
+
+
+def all_pairs_distance(g, nodelist, weight="weight"):
+    """All-pairs shortest-path distance matrix for ``g``, ordered by
+    ``nodelist``. ``weight=None`` treats every edge as weight 1 (hop
+    count); ``weight="weight"`` (default) uses ``g``'s edge weights.
+    Unreachable pairs are ``inf``, matching ``nx.floyd_warshall_numpy``.
+    """
+    adj = nx.to_scipy_sparse_array(g, nodelist=nodelist, weight=weight, dtype=float)
+    return shortest_path(adj, method="auto", directed=True)

tmapper_py-0.1.0/src/tmapper/app/__init__.py

@@ -0,0 +1,10 @@
+"""The interactive Streamlit app, and its launcher.
+
+Lives inside the package so that ``pip install "tmapper[app]"`` ships it --
+otherwise the app would only be runnable from a clone of the repository,
+which is exactly the friction it exists to remove.
+"""
+
+from .launcher import main
+
+__all__ = ["main"]

tmapper_py-0.1.0/src/tmapper/app/launcher.py

@@ -0,0 +1,35 @@
+"""Console-script entry point: ``tmapper-app``.
+
+A Streamlit app is a *script Streamlit runs*, not a program you import and
+call, so this hands the app file to Streamlit's own CLI rather than
+executing it directly -- running it as a plain script would just print
+Streamlit's "missing ScriptRunContext" warnings and do nothing useful.
+
+Any extra arguments are passed straight through, so the usual Streamlit
+options still work::
+
+    tmapper-app --server.port 8600 --server.address 0.0.0.0
+"""
+
+import sys
+from pathlib import Path
+
+APP_FILE = Path(__file__).resolve().parent / "streamlit_app.py"
+
+
+def main(argv=None):
+    try:
+        from streamlit.web import cli as stcli
+    except ImportError:  # pragma: no cover - depends on install extras
+        raise SystemExit(
+            "The interactive app needs Streamlit, which is not installed.\n"
+            "Install it with:  pip install 'tmapper[app]'"
+        )
+
+    args = sys.argv[1:] if argv is None else list(argv)
+    sys.argv = ["streamlit", "run", str(APP_FILE), *args]
+    return stcli.main()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())