treegraphduals 0.1.0__tar.gz

treegraphduals-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+.idea
+.claude/settings.local.json
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.coverage
+coverage.json
+htmlcov/
+docs/_build/
+.venv/
+venv/
+build/
+dist/
+.mypy_cache/
+.ruff_cache/
+.env
+docs/coverage_report.md
+docs/test_results.txt

treegraphduals-0.1.0/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to this project are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+### Fixed
+- Docstring tree diagrams rendered mangled: 15 docstrings were not raw strings,
+  so a trailing `\` in the ASCII art silently swallowed the following newline
+  and joined rows together (`/ \` + `1   2` became `/             1   2`). The
+  art in the source was correct all along. Diagrams are now raw strings inside
+  RST literal blocks, and the Horton pruning and Horton-Strahler examples are
+  redrawn from what the algorithms actually produce.
+- The Sphinx build is now warning-free (was 84 warnings).
+- Symbolic extrema search (`TimeSeries.from_function(..., preserve_extrema=True)`)
+  no longer silently discards critical points:
+  - Real roots that sympy returns in complex form (Cardano's formula writes the
+    three real roots of a cubic using `I`) were dropped, because the reality test
+    was "does `float()` succeed". Reality is now decided by the magnitude of the
+    imaginary part, so e.g. `t**4/4 - 2*t**2 + t/3` reports its three extrema
+    instead of none.
+  - Periodic derivatives only ever produced sympy's principal solutions, so
+    `sin(t)` on `[0, 10]` lost its maximum at `5*pi/2`. Critical points are now
+    solved over the interval, which enumerates the periodic solutions.
+- `plot_tree_and_harris_path` no longer leaks one matplotlib figure per call
+  (pyplot kept every discarded `plot_tree` figure alive), and now draws the tree
+  into its left axes instead of a "Tree plot" placeholder.
+
+### Changed
+- README reorganized into what the package computes today versus what is
+  planned. Every original bullet is preserved; the previous single list mixed
+  25+ unimplemented features (duals, visibility graphs, merge trees, graph
+  metrics) with the 7 that work, and it is the PyPI long description.
+
+### Added
+- `tests/test_timeseries.py`: regression tests for the extrema cases above, the
+  numerical fallback path, uniform sampling, and level-set tree construction.
+- Packaging: Hatchling build backend, so the project can be built and published
+  (`uv build`). Ships `py.typed`, the MIT license file, README as the long
+  description, classifiers, keywords and project URLs.
+
+### Changed
+- **Breaking:** moved `core`, `timeseries`, `visualizations` and `agents` under a
+  single `src/treegraphduals/` package. Imports are now
+  `from treegraphduals.core import Tree` rather than `from core import Tree`,
+  so the library no longer claims generic top-level names.
+- `requires-python` raised to `>=3.12`, matching what CI and Read the Docs test.
+- Test and documentation tooling moved out of runtime dependencies into the `dev`
+  and `docs` dependency groups; a plain `pip install treegraphduals` no longer
+  pulls in pytest and Sphinx.
+- Doctests now run by default: `testpaths` covers `src` as well as `tests`, so the
+  `--doctest-modules` flag in CI is no longer a no-op (62 tests, up from 40).
+- `docs/conf.py` reads the version from package metadata instead of hardcoding it,
+  and no longer injects an absolute local path for doctest setup.
+- Replaced a `print` with `warnings.warn` when symbolic differentiation falls back
+  to the numerical extrema search.
+- Cleared the Ruff backlog (56 findings): added missing module and magic-method
+  docstrings, made ASCII-art docstrings raw so the diagrams render literally,
+  replaced implicit `Optional` annotations, narrowed a bare `except`, collapsed
+  nested conditionals, sorted `__all__` lists, and dropped dead locals.
+
+## [0.1.0] - 2026-09-18
+### Added
+- Initial project setup: `uv` packaging, Ruff lint/format, Pyrefly type checking, pytest + Hypothesis + coverage, Sphinx docs on Read the Docs, `CITATION.cff` with Zenodo DOI, pre-commit hooks.

treegraphduals-0.1.0/CITATION.cff

@@ -0,0 +1,28 @@
+cff-version: 1.2.0
+message: "If you use this software in your work, please cite it as below."
+title: "treegraphduals"
+version: "0.1.0"
+date-released: "2026-09-19"
+authors:
+  - family-names: "Khan"
+    given-names: "Ibraheem"
+    orcid: "https://orcid.org/0009-0002-5697-0682"
+url: "https://github.com/pikhan/treegraphduals"
+repository-code: "https://github.com/pikhan/treegraphduals"
+identifiers:
+  - type: doi
+    value: 10.5281/zenodo.22839827
+    description: "The concept DOI representing all versions of this work."
+preferred-citation:
+  type: thesis
+  thesis-type: "Master's Thesis"
+  title: "The Horizontal Tunnelability Graph is Dual to Level Set Trees"
+  authors:
+    - family-names: "Khan"
+      given-names: "Ibraheem"
+      orcid: "https://orcid.org/0009-0002-5697-0682"
+  institution:
+    name: "University of Nevada, Reno"
+  year: 2023
+  month: 9
+  url: "http://hdl.handle.net/11714/10548"

treegraphduals-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+
+
+Copyright 2024, Ibraheem Mehdi Khan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

treegraphduals-0.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.5
+Name: treegraphduals
+Version: 0.1.0
+Summary: Trees, their duals, graphs, and time series: level-set trees, Harris paths, Horton-Strahler pruning, and horizontal tunnelability graphs.
+Project-URL: Homepage, https://github.com/pikhan/treegraphduals
+Project-URL: Repository, https://github.com/pikhan/treegraphduals
+Project-URL: Documentation, https://treegraphduals.readthedocs.io
+Project-URL: Changelog, https://github.com/pikhan/treegraphduals/blob/main/CHANGELOG.md
+Project-URL: Thesis, http://hdl.handle.net/11714/10548
+Project-URL: Zenodo, https://doi.org/10.5281/zenodo.22839827
+Author-email: Ibraheem Mehdi Khan <polymathykhan@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: duality,graphs,harris paths,horton-strahler,level-set trees,random self-similar trees,time series,trees
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: igraph>=0.11
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: networkx>=3.2
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.11
+Requires-Dist: sympy>=1.12
+Description-Content-Type: text/markdown
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22839827.svg)](https://doi.org/10.5281/zenodo.22839827)
+[![Docs](https://readthedocs.org/projects/treegraphduals/badge/?version=latest)](https://treegraphduals.readthedocs.io/en/latest/)
+
+# treegraphduals
+
+This package is an extension of my Master's thesis: [The Horizontal Tunnelability Graph is Dual to Level Set Trees](http://hdl.handle.net/11714/10548).
+I have tried to keep everything as compatible as possible with other popular time series, tree, and graph libraries.
+
+This is an early release. The sections below separate what the package computes
+today from what it is being built towards, so you can tell at a glance whether
+the piece you need is ready.
+
+## Install
+
+```bash
+pip install treegraphduals     # or: uv add treegraphduals
+```
+
+Requires Python 3.12+.
+
+## Quickstart
+
+```python
+from treegraphduals.core import Tree
+from treegraphduals.timeseries import TimeSeries
+
+# Level-set tree of a time series
+ts = TimeSeries.from_array([0, 3, 1, 4, 2, 5, 0])
+tree = ts.to_level_set_tree()
+tree  # Tree(n_nodes=6, n_leaves=3, root=0)
+tree.horton_strahler_order_tree()  # 2
+tree.max_horton_prunings()  # 3
+
+# Level-set tree of a symbolic function, using exact critical points
+import sympy as sp
+
+t = sp.Symbol("t")
+extrema = TimeSeries.from_function(
+    (t - 1) * (t - 3) * (t - 5) * (t - 7), 1, 7, preserve_extrema=True
+)
+extrema.times  # [1.0, 1.764, 4.0, 6.236, 7.0]
+
+# Hand the result to NetworkX or igraph
+G = tree.to_networkx()  # DiGraph with 6 nodes and 5 edges
+```
+
+## What the package computes today
+
+**Time series to trees**
+
+- Level Set Trees of Time Series as Alternating Piecewise Linear Excursions with Slopes +/- 1 (Harris Paths)
+- Level Set Trees of Time Series as Alternating Piecewise Linear Excursions of Arbitrary Slope
+- Level Set Trees and Partial Trees of Arbitrary Time Series
+- Level Set Trees of Arbitrary Functions via Sympy, using exact symbolic differentiation
+- Harris Paths of Binary Trees (and Partial Trees)
+- Local extrema detection, minimal excursions, and unit-slope excursions
+
+**Trees**
+
+- Horton-Strahler Orders of a Binary Tree, and of a tree as a whole
+- Horton Pruning of a Tree, with series reduction, and the pruning count to eliminate a tree
+- Plantedness, leaves, internal nodes, depths, subtree sizes, total length
+- Traversals: depth-first, breadth-first, left-to-right, and edge contours
+- Paths, distances, and ancestry queries between any two nodes
+- Structures: `Tree`, `BinaryTree`, `Forest`, `DAG`, `Polytree`, `Graph`, `Multigraph`, `ErdosRenyi`, `GaltonWatsonTree`, `RealTree`
+
+Trees may be weighted or unweighted.
+
+**Interoperability** — every structure converts to and from
+
+- NetworkX and igraph graphs
+- NumPy adjacency matrices and SciPy sparse matrices
+- Parent arrays, with left/right child information preserved for binary trees
+
+This is the intended route to general graph-theoretic quantities for now:
+export to NetworkX or igraph and use their algorithms.
+
+**Visualization**
+
+- Tree plots with disk (for duality), radial, force-directed, and hierarchical layouts
+- Coloring by Horton-Strahler order, with node and edge annotations
+- Time series, excursion, and extrema plots
+- Trees drawn side by side with their Harris path
+
+## Planned
+
+None of the following is implemented yet. They are the roadmap, listed here
+because they are where the package is going, not what it does now.
+
+**Duals and visibility graphs**
+
+- Duals of Binary Trees (Horizontal Tunnelability Graphs)
+- Duals of Binary Trees w/ Partial Trees
+- Dual of a Graph
+- Horizontal Visibility Graphs of Piecewise Linear Excursions, Arbitrary Time Series, and Arbitrary Functions
+- Horizon Visibility Graphs of Piecewise Linear Excursions, Arbitrary Time Series, and Arbitrary Functions
+- Visibility Graphs of Piecewise Linear Excursions, Arbitrary Time Series, and Arbitrary Functions
+
+**Further tree and time series constructions**
+
+- Time Series Merge Trees of Arbitrary Time Series and of Arbitrary Functions
+- Chiral Merge Trees of Arbitrary Time Series and of Arbitrary Functions
+- U-shaped Segments of Arbitrary Time Series and of Arbitrary Functions
+- Hurst Exponents
+- Persistence Diagrams/Barcodes
+- Time-varying trees, and hence time-varying duals, with appropriate interpretation on time series
+
+**Native graph functionality**
+
+The graph classes are intended to become general enough to allow for:
+
+- Vertices with or without numerical weights as well as optional labels of arbitrary data type
+- Directed or undirected Edges with or without numerical weights and optional labels of arbitrary data type
+- Easy and efficient recall/computation of other graph representations and important quantities such as
+- Adjacency Matrix, Incidence Matrix, Adjacency List, Laplacian Matrix, Graph Distance Matrix, etc.
+- Graph Traversal Algorithms: DFS and BFS
+- Find Shortest Path, Shortest Path Function, Hamiltonian Path, Topological Sort
+- Find Graph Distances, Find Paths (Edge/Vertex Independent as well), Find Cycles (All, Eulerian, Hamiltonian, Postman, Shortest Tour)
+- Check if two Graphs are Isomorphic
+- Graph Union, Find Maximum Flow, Path Lengths, Mean Path Lengths, etc.
+- Compute Graph Polynomials: Tutte, Chromatic, Flow
+- Check if a Graph is a Subgraph of Another Graph
+- Generate Neighborhood Graphs and Subgraphs from Graphs
+- Get Connected Components of a Graph, k-Core Components, Weakly Connected Components
+- Find Cliques
+- Check if a Graph is a Tree (and if so how k-ary), if it is Acyclic, Bipartite, Planar, Loop Free, Simple, etc.
+- Graph Self-Similarity, Small-World Property, Scale-Invariance
+- Graph Metrics: Vertex and Edge Count, Vertex Degree/In and Out Degrees, Vertex Eccentricity
+- Graph Radius, Graph Diameter, Graph Center, Graph Periphery, Vertex and Edge Connectivity
+- Centrality Measures: Closeness, Betweenness, Edge Betweenness, Degree Centrality, Eigenvector Centrality, Katz Centrality, PageRank Centrality, HITS Centrality, Radiality, Status Centrality
+- Reciprocity and Transitivity Measures: Graph Reciprocity & Global, Local, and Mean Clustering Coefficients
+- Homophily, Assortative Mixing, and Similarity Measures: Assortativity, Vertex Correlation, Mean Neighbor Degree
+- Mean Degree Connectivity, Vertex Dice Similarity, Vertex Jaccard Similarity, Vertex Cosine Similarity
+- Mean Degree, Mean Path Length, Clustering Coefficients, Degree Distributions, Degree Sequences, many many other things
+
+## Documentation
+
+Full API documentation, tutorials, and examples: <https://treegraphduals.readthedocs.io>
+
+## Citing
+
+If you use this package, please cite it via the DOI above, or see
+[`CITATION.cff`](CITATION.cff). The underlying thesis is
+*The Horizontal Tunnelability Graph is Dual to Level Set Trees*
+(University of Nevada, Reno, 2023).
+
+## License
+
+MIT

treegraphduals-0.1.0/README.md

@@ -0,0 +1,149 @@
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22839827.svg)](https://doi.org/10.5281/zenodo.22839827)
+[![Docs](https://readthedocs.org/projects/treegraphduals/badge/?version=latest)](https://treegraphduals.readthedocs.io/en/latest/)
+
+# treegraphduals
+
+This package is an extension of my Master's thesis: [The Horizontal Tunnelability Graph is Dual to Level Set Trees](http://hdl.handle.net/11714/10548).
+I have tried to keep everything as compatible as possible with other popular time series, tree, and graph libraries.
+
+This is an early release. The sections below separate what the package computes
+today from what it is being built towards, so you can tell at a glance whether
+the piece you need is ready.
+
+## Install
+
+```bash
+pip install treegraphduals     # or: uv add treegraphduals
+```
+
+Requires Python 3.12+.
+
+## Quickstart
+
+```python
+from treegraphduals.core import Tree
+from treegraphduals.timeseries import TimeSeries
+
+# Level-set tree of a time series
+ts = TimeSeries.from_array([0, 3, 1, 4, 2, 5, 0])
+tree = ts.to_level_set_tree()
+tree  # Tree(n_nodes=6, n_leaves=3, root=0)
+tree.horton_strahler_order_tree()  # 2
+tree.max_horton_prunings()  # 3
+
+# Level-set tree of a symbolic function, using exact critical points
+import sympy as sp
+
+t = sp.Symbol("t")
+extrema = TimeSeries.from_function(
+    (t - 1) * (t - 3) * (t - 5) * (t - 7), 1, 7, preserve_extrema=True
+)
+extrema.times  # [1.0, 1.764, 4.0, 6.236, 7.0]
+
+# Hand the result to NetworkX or igraph
+G = tree.to_networkx()  # DiGraph with 6 nodes and 5 edges
+```
+
+## What the package computes today
+
+**Time series to trees**
+
+- Level Set Trees of Time Series as Alternating Piecewise Linear Excursions with Slopes +/- 1 (Harris Paths)
+- Level Set Trees of Time Series as Alternating Piecewise Linear Excursions of Arbitrary Slope
+- Level Set Trees and Partial Trees of Arbitrary Time Series
+- Level Set Trees of Arbitrary Functions via Sympy, using exact symbolic differentiation
+- Harris Paths of Binary Trees (and Partial Trees)
+- Local extrema detection, minimal excursions, and unit-slope excursions
+
+**Trees**
+
+- Horton-Strahler Orders of a Binary Tree, and of a tree as a whole
+- Horton Pruning of a Tree, with series reduction, and the pruning count to eliminate a tree
+- Plantedness, leaves, internal nodes, depths, subtree sizes, total length
+- Traversals: depth-first, breadth-first, left-to-right, and edge contours
+- Paths, distances, and ancestry queries between any two nodes
+- Structures: `Tree`, `BinaryTree`, `Forest`, `DAG`, `Polytree`, `Graph`, `Multigraph`, `ErdosRenyi`, `GaltonWatsonTree`, `RealTree`
+
+Trees may be weighted or unweighted.
+
+**Interoperability** — every structure converts to and from
+
+- NetworkX and igraph graphs
+- NumPy adjacency matrices and SciPy sparse matrices
+- Parent arrays, with left/right child information preserved for binary trees
+
+This is the intended route to general graph-theoretic quantities for now:
+export to NetworkX or igraph and use their algorithms.
+
+**Visualization**
+
+- Tree plots with disk (for duality), radial, force-directed, and hierarchical layouts
+- Coloring by Horton-Strahler order, with node and edge annotations
+- Time series, excursion, and extrema plots
+- Trees drawn side by side with their Harris path
+
+## Planned
+
+None of the following is implemented yet. They are the roadmap, listed here
+because they are where the package is going, not what it does now.
+
+**Duals and visibility graphs**
+
+- Duals of Binary Trees (Horizontal Tunnelability Graphs)
+- Duals of Binary Trees w/ Partial Trees
+- Dual of a Graph
+- Horizontal Visibility Graphs of Piecewise Linear Excursions, Arbitrary Time Series, and Arbitrary Functions
+- Horizon Visibility Graphs of Piecewise Linear Excursions, Arbitrary Time Series, and Arbitrary Functions
+- Visibility Graphs of Piecewise Linear Excursions, Arbitrary Time Series, and Arbitrary Functions
+
+**Further tree and time series constructions**
+
+- Time Series Merge Trees of Arbitrary Time Series and of Arbitrary Functions
+- Chiral Merge Trees of Arbitrary Time Series and of Arbitrary Functions
+- U-shaped Segments of Arbitrary Time Series and of Arbitrary Functions
+- Hurst Exponents
+- Persistence Diagrams/Barcodes
+- Time-varying trees, and hence time-varying duals, with appropriate interpretation on time series
+
+**Native graph functionality**
+
+The graph classes are intended to become general enough to allow for:
+
+- Vertices with or without numerical weights as well as optional labels of arbitrary data type
+- Directed or undirected Edges with or without numerical weights and optional labels of arbitrary data type
+- Easy and efficient recall/computation of other graph representations and important quantities such as
+- Adjacency Matrix, Incidence Matrix, Adjacency List, Laplacian Matrix, Graph Distance Matrix, etc.
+- Graph Traversal Algorithms: DFS and BFS
+- Find Shortest Path, Shortest Path Function, Hamiltonian Path, Topological Sort
+- Find Graph Distances, Find Paths (Edge/Vertex Independent as well), Find Cycles (All, Eulerian, Hamiltonian, Postman, Shortest Tour)
+- Check if two Graphs are Isomorphic
+- Graph Union, Find Maximum Flow, Path Lengths, Mean Path Lengths, etc.
+- Compute Graph Polynomials: Tutte, Chromatic, Flow
+- Check if a Graph is a Subgraph of Another Graph
+- Generate Neighborhood Graphs and Subgraphs from Graphs
+- Get Connected Components of a Graph, k-Core Components, Weakly Connected Components
+- Find Cliques
+- Check if a Graph is a Tree (and if so how k-ary), if it is Acyclic, Bipartite, Planar, Loop Free, Simple, etc.
+- Graph Self-Similarity, Small-World Property, Scale-Invariance
+- Graph Metrics: Vertex and Edge Count, Vertex Degree/In and Out Degrees, Vertex Eccentricity
+- Graph Radius, Graph Diameter, Graph Center, Graph Periphery, Vertex and Edge Connectivity
+- Centrality Measures: Closeness, Betweenness, Edge Betweenness, Degree Centrality, Eigenvector Centrality, Katz Centrality, PageRank Centrality, HITS Centrality, Radiality, Status Centrality
+- Reciprocity and Transitivity Measures: Graph Reciprocity & Global, Local, and Mean Clustering Coefficients
+- Homophily, Assortative Mixing, and Similarity Measures: Assortativity, Vertex Correlation, Mean Neighbor Degree
+- Mean Degree Connectivity, Vertex Dice Similarity, Vertex Jaccard Similarity, Vertex Cosine Similarity
+- Mean Degree, Mean Path Length, Clustering Coefficients, Degree Distributions, Degree Sequences, many many other things
+
+## Documentation
+
+Full API documentation, tutorials, and examples: <https://treegraphduals.readthedocs.io>
+
+## Citing
+
+If you use this package, please cite it via the DOI above, or see
+[`CITATION.cff`](CITATION.cff). The underlying thesis is
+*The Horizontal Tunnelability Graph is Dual to Level Set Trees*
+(University of Nevada, Reno, 2023).
+
+## License
+
+MIT

treegraphduals-0.1.0/docs/Makefile

@@ -0,0 +1,69 @@
+# Makefile for Sphinx documentation with integrated testing
+
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+PYTEST        = pytest
+COVERAGE      = coverage
+
+.PHONY: help clean html test coverage docs-with-tests
+
+help:
+	@echo "Please use 'make <target>' where <target> is one of"
+	@echo "  html             Build HTML documentation only"
+	@echo "  test             Run tests only"
+	@echo "  coverage         Run tests with coverage only"
+	@echo "  docs-with-tests  Run tests + coverage + build docs (RECOMMENDED)"
+	@echo "  clean            Remove build artifacts"
+
+clean:
+	rm -rf $(BUILDDIR)/*
+	rm -rf ../htmlcov
+	rm -rf ../.coverage
+	rm -rf ../.pytest_cache
+	rm -f coverage_report.md test_results.txt
+
+test:
+	@echo "Running pytest..."
+	cd .. && $(PYTEST) -v
+
+coverage:
+	@echo "Running pytest with coverage..."
+	cd .. && $(PYTEST) --cov=treegraphduals --cov-report=html --cov-report=term -v
+
+docs-with-tests:
+	@echo "========================================="
+	@echo "Running Tests & Building Documentation"
+	@echo "========================================="
+	@echo ""
+	@echo "Step 1: Running all tests with coverage..."
+	cd .. && $(PYTEST) --cov=treegraphduals \
+	                    --cov-report=html \
+	                    --cov-report=term \
+	                    --cov-report=json \
+	                    --cov-report=markdown:docs/coverage_report.md \
+	                    --doctest-modules \
+	                    -v --tb=short | tee docs/test_results.txt
+	@echo ""
+	@echo "Step 2: Building Sphinx documentation..."
+	$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS)
+	@echo ""
+	@echo "Step 3: Copying coverage HTML..."
+	@if [ -d "../htmlcov" ]; then \
+		cp -r ../htmlcov $(BUILDDIR)/html/; \
+		echo "Coverage report copied to _build/html/htmlcov/"; \
+	fi
+	@echo ""
+	@echo "========================================="
+	@echo "Done!"
+	@echo "Open: $(BUILDDIR)/html/index.html"
+	@echo "Coverage: $(BUILDDIR)/html/htmlcov/index.html"
+	@echo "========================================="
+
+html: clean
+	$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS)
+
+# Catch-all target
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

treegraphduals-0.1.0/docs/api/core.rst

@@ -0,0 +1,9 @@
+Core Module
+===========
+
+The core module provides the fundamental graph data structures.
+
+.. automodule:: treegraphduals.core
+   :members:
+   :undoc-members:
+   :show-inheritance:

treegraphduals-0.1.0/docs/api/timeseries.rst

@@ -0,0 +1,23 @@
+Time Series Module
+==================
+
+The time series module provides the fundamental time series data structures and tools for manipulation/analysis.
+
+.. autoclass:: treegraphduals.timeseries.TimeSeries
+   :members:
+   :inherited-members:
+   :show-inheritance:
+
+Conversion Functions
+--------------------
+
+.. autofunction:: treegraphduals.timeseries.timeseries_to_tree
+
+.. autofunction:: treegraphduals.timeseries.tree_to_timeseries
+
+.. autofunction:: treegraphduals.timeseries.tree_to_harris_path
+
+Utilities
+---------
+
+.. autofunction:: treegraphduals.timeseries.detect_local_extrema

treegraphduals-0.1.0/docs/api/visualizations.rst

@@ -0,0 +1,33 @@
+Visualizations Module
+=====================
+
+The visualizations module provides the main methods for visualizing trees, graphs, time series, duals, etc.
+
+Tree Plotting
+-------------
+
+.. autofunction:: treegraphduals.visualizations.plot_tree
+
+.. autofunction:: treegraphduals.visualizations.color_by_horton_strahler
+
+.. autofunction:: treegraphduals.visualizations.add_node_annotation
+
+.. autofunction:: treegraphduals.visualizations.add_edge_annotation
+
+Time Series Plotting
+--------------------
+
+.. autofunction:: treegraphduals.visualizations.plot_timeseries
+
+.. autofunction:: treegraphduals.visualizations.plot_timeseries_with_extrema
+
+.. autofunction:: treegraphduals.visualizations.plot_excursion
+
+Combined Visualizations
+-----------------------
+
+.. autofunction:: treegraphduals.visualizations.plot_tree_and_harris_path
+
+.. autofunction:: treegraphduals.visualizations.plot_levelset_overlay
+
+.. autofunction:: treegraphduals.visualizations.plot_graph_overlay

treegraphduals-0.1.0/docs/changelog.md

@@ -0,0 +1,5 @@
+# Changelog
+
+```{include} ../CHANGELOG.md
+:start-line: 1
+```