Update readme

.gitignore

@@ -8,6 +8,9 @@ benchmarks/results/*
 src/ect/embed_graph.py
 src/ect/embed_cw.py
 
+.conda*
+.vscode/*
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

README.md

@@ -1,10 +1,16 @@
 # `ect`: A python package for computing the Euler Characteristic Transform
 
-Python computation tools for computing the Euler Characteristic Transform of embedded graphs. 
+Python computation tools for computing the Euler Characteristic Transform of embedded complexes. 
 
 ## Description
 
-Right now, the content includes stuff for doing ECT on graphs embedded in 2D. Eventually the goal is to get voxel versions, higher dimensional simplicial complexes, etc in here.
+The package provides fast tools for computing the Euler Characteristic Transform (ECT) on embedded cell complexes in any ambient dimension. You build a complex (vertices, edges, and optional higher‑dimensional cells), choose a set of directions and thresholds, and compute either the exact ECT or its smoothed/differentiable variants. Results come back as NumPy arrays with metadata, plotting helpers, and distance utilities, making it straightforward to visualize transforms and compare shapes. The core is implemented with NumPy and Numba, with optional validation of geometric and structural constraints when constructing complexes.
+
+- `EmbeddedComplex`: convert point clouds into complexes with vertices, edges, and higher‑dimensional cells with embedded coordinates.
+- `ECT`, `SECT`, `DECT` : ECT calculations along with the smooth and differentiable variants over sampled directions and transforms.
+- `Directions`: uniform, random, or custom directions (angles in 2D; vectors in any dimension)
+- Results as `ECTResult`: behaves like a NumPy array, with plotting and distance helpers
+- Optional geometric/structural validation when building complexes
 
 For more information on the ECT, see:
 
@@ -17,16 +23,12 @@ For more information on the ECT, see:
 - The documentation is available at: [munchlab.github.io/ect](https://munchlab.github.io/ect/)
 - A tutorial jupyter notebook can be found [here](https://munchlab.github.io/ect/notebooks/Tutorial-ECT_for_embedded_graphs.html)
 
-### Dependencies
-
-- `networkx`
-- `numpy`
-- `matplotlib`
-- `numba`
 
 ### Installing
 
-The package can be installed using pip:
+Requires Python 3.10+.
+
+Install from PyPI:
 
 ```{bash}
 pip install ect
@@ -40,6 +42,28 @@ cd ect
 pip install .
 ```
 
+### Quickstart
+
+Compute an ECT for a simple embedded triangle and plot it.
+
+```python
+from ect import ECT, EmbeddedComplex
+
+G = EmbeddedComplex()
+G.add_node("a", [0.0, 0.0])
+G.add_node("b", [1.0, 0.0])
+G.add_node("c", [0.5, 0.8])
+G.add_edge("a", "b")
+G.add_edge("b", "c")
+G.add_edge("c", "a")
+
+ect = ECT(num_dirs=32, num_thresh=128)
+result = ect.calculate(G)
+result.plot()
+```
+
+
+
 ## Authors
 
 This code was written by [Liz Munch](https://elizabethmunch.com/) along with her research group and collaborators. People who have contributed to `ect` include:

paper/paper.bib

@@ -0,0 +1,173 @@
+@book{Dey2021,
+  author    = {Dey, Tamal K. and Wang, Yusu},
+  publisher = {Cambridge University Press},
+  title     = {Computational Topology for Data Analysis},
+  year      = {2021},
+  file      = {:MathTextbooks/DeyWang-CTDAbook.pdf:PDF}
+}
+
+@article{Munch2017,
+  author       = {Elizabeth Munch},
+  journal      = {Journal of Learning Analytics},
+  title        = {A User's Guide to Topological Data Analysis},
+  year         = {2017},
+  number       = {2},
+  volume       = {4},
+  abstract     = {Topological data analysis (TDA) is a collection of powerful tools that can quantify shape and structure in data in order to answer questions from the data's domain. This is done by representing some aspect of the structure of the data in a simplified topological signature. In this article, we introduce two of the most commonly used topological signatures. First, the persistence diagram represents loops and holes in the space by considering connectivity of the data points for a continuum of values rather than a single fixed value. The second topological signature, the mapper graph, returns a 1-dimensional structure representing the shape of the data, and is particularly good for exploration and visualization of the data. While these techniques are based on very sophisticated mathematics, the current ubiquity of available software means that these tools are more accessible than ever to be applied to data by researchers in education and learning, as well as all domain scientists.},
+  creationdate = {2018-05-30T00:00:00},
+  doi          = {10.18608/jla.2017.42.6}
+}
+
+@book{Hatcher,
+  author       = {Allen Hatcher},
+  publisher    = {Cambridge University Press},
+  title        = {Algebraic Topology},
+  year         = {2002},
+  creationdate = {2011-05-23T00:00:00},
+  file         = {Hatcher - algebraic topology.pdf:MathTextbooks/Hatcher - algebraic topology.pdf:PDF},
+  groups       = {Classic Textbooks},
+  owner        = {liz}
+}
+
+@article{Munch2025,
+  author        = {Munch, Elizabeth},
+  journal       = {The American Mathematical Monthly},
+  title         = {An Invitation to the Euler Characteristic Transform},
+  year          = {2025},
+  number        = {1},
+  pages         = {15--25},
+  volume        = {132},
+  abstract      = {The Euler characteristic transform (ECT) is a simple to define yet powerful representation of shape. The idea is to encode an embedded shape using sub-level sets of a a function defined based on a given direction, and then returning the Euler characteristics of these sublevel sets. Because the ECT has been shown to be injective on the space of embedded simplicial complexes, it has been used for applications spanning a range of disciplines, including plant morphology and protein structural analysis. In this survey article, we present a comprehensive overview of the Euler characteristic transform, highlighting the main idea on a simple leaf example, and surveying its its key concepts, theoretical foundations, and available applications.},
+  archiveprefix = {arXiv},
+  comment       = {The work of EM is funded in part by the National Science Foundation through CCF-1907591, CCF-2106578, CCF-2142713, IOS-2310355, IOS-2310356, and IOS-2310357.},
+  copyright     = {arXiv.org perpetual, non-exclusive license},
+  doi           = {10.1080/00029890.2024.2409616},
+  eprint        = {2310.10395},
+  file          = {:Munch2023 - An Invitation to the Euler Characteristic Transform.pdf:PDF},
+  image         = {Munch2023.png},
+  keywords      = {Computational Geometry (cs.CG),FOS: Computer and information sciences,journal},
+  primaryclass  = {cs.CG},
+  publisher     = {Taylor \& Francis}
+}
+
+@article{Turner2014,
+  author       = {K. Turner and S. Mukherjee and D. M. Boyer},
+  journal      = {Information and Inference},
+  title        = {Persistent homology transform for modeling shapes and surfaces},
+  year         = {2014},
+  month        = {Dec},
+  number       = {4},
+  pages        = {310--344},
+  volume       = {3},
+  comment      = {Requested copy from the MSU Library, 3/22/18},
+  creationdate = {2018-03-22T00:00:00},
+  doi          = {10.1093/imaiai/iau011},
+  file         = {:Persistence/Turner2014a_Published.pdf:PDF;:Persistence/Turner2014a.pdf:PDF;:Persistence/Turner2014a_ErikSlides.pdf:PDF},
+  priority     = {prio1},
+  publisher    = {Oxford University Press ({OUP})},
+  readstatus   = {read}
+}
+
+@article{Crawford2019,
+  author    = {Lorin Crawford and Anthea Monod and Andrew X. Chen and Sayan Mukherjee and Ra{\'{u}}l Rabad{\'{a}}n},
+  journal   = {Journal of the American Statistical Association},
+  title     = {Predicting Clinical Outcomes in Glioblastoma: An Application of Topological and Functional Data Analysis},
+  year      = {2019},
+  month     = {Oct},
+  number    = {531},
+  pages     = {1139--1150},
+  volume    = {115},
+  doi       = {10.1080/01621459.2019.1671198},
+  file      = {:DirectionalTransform/Crawford2019.pdf:PDF},
+  publisher = {Informa {UK} Limited}
+}
+
+@article{Meng2022,
+  author        = {Meng, Kun and Wang, Jinyu and Crawford, Lorin and Eloyan, Ani},
+  journal       = {arXiv:2204.12699},
+  title         = {Randomness and Statistical Inference of Shapes via the Smooth {E}uler Characteristic Transform},
+  year          = {2022},
+  month         = {Apr},
+  abstract      = {In this paper, we provide the foundations for deriving the distributional properties of the smooth Euler characteristic transform. Motivated by functional data analysis, we propose two algorithms for testing hypotheses on random shapes based on these foundations. Simulation studies are provided to support our mathematical derivations and show the performance of our hypothesis testing framework. We apply our proposed algorithms to analyze a data set of mandibular molars from four genera of primates to test for shape differences and interpret the corresponding results from the morphology viewpoint. Our discussions connect the following fields: algebraic and computational topology, probability theory and stochastic processes, Sobolev spaces and functional analysis, statistical inference, morphology, and medical imaging.},
+  archiveprefix = {arXiv},
+  copyright     = {arXiv.org perpetual, non-exclusive license},
+  doi           = {10.48550/ARXIV.2204.12699},
+  eprint        = {2204.12699},
+  file          = {:Meng2022 - Randomness and Statistical Inference of Shapes Via the Smooth Euler Characteristic Transform.pdf:PDF:http\://arxiv.org/pdf/2204.12699v2;:DirectionalTransform/Meng2022.pdf:PDF},
+  keywords      = {Methodology (stat.ME), FOS: Computer and information sciences},
+  primaryclass  = {stat.ME},
+  publisher     = {arXiv}
+}
+
+@book{Mardia1999,
+  author    = {Mardia, Kanti V. and Jupp, Peter E.},
+  publisher = {Wiley},
+  title     = {Directional Statistics},
+  year      = {1999},
+  isbn      = {9780470316979},
+  month     = jan,
+  doi       = {10.1002/9780470316979},
+  issn      = {1940-6347},
+  journal   = {Wiley Series in Probability and Statistics}
+}
+
+@article{Wasserman2018,
+  author       = {Larry Wasserman},
+  journal      = {Annual Review of Statistics and Its Application},
+  title        = {Topological Data Analysis},
+  year         = {2018},
+  month        = {mar},
+  number       = {1},
+  pages        = {501--532},
+  volume       = {5},
+  creationdate = {2018-04-12T00:00:00},
+  doi          = {10.1146/annurev-statistics-031017-100045},
+  file         = {:Persistence/PersistenceSurveys/Wasserman2018.pdf:PDF},
+  keywords     = {survey, statistics, persistence},
+  priority     = {prio1},
+  publisher    = {Annual Reviews}
+}
+
+@book{Ghrist2014,
+  title    = {Elementary Applied Topology},
+  year     = {2014},
+  author   = {Robert Ghrist},
+  keywords = {textbook, survey}
+}
+
+@book{Goodman2018,
+  editor    = {Jacob E. Goodman and Joseph O'Rourke and Csaba D. Tóth},
+  publisher = {CRC Press},
+  title     = {Handbook of discrete and computational geometry},
+  year      = {2018},
+  address   = {Boca Raton},
+  edition   = {Third edition},
+  isbn      = {9781351645911},
+  series    = {Discrete mathematics and its applications},
+  pagetotal = {11928},
+  ppn_gvk   = {1007357088}
+}
+
+@inproceedings{Roell2024,
+  author    = {Ernst R{\"o}ell and Bastian Rieck},
+  booktitle = {The Twelfth International Conference on Learning Representations},
+  title     = {Differentiable Euler Characteristic Transforms for Shape Classification},
+  year      = {2024},
+  url       = {https://openreview.net/forum?id=MO632iPq3I}
+}
+
+@article{Rieck2024,
+  author        = {Rieck, Bastian},
+  title         = {Topology meets Machine Learning: An Introduction using the Euler Characteristic Transform},
+  year          = {2024},
+  month         = oct,
+  abstract      = {This overview article makes the case for how topological concepts can enrich research in machine learning. Using the Euler Characteristic Transform (ECT), a geometrical-topological invariant, as a running example, I present different use cases that result in more efficient models for analyzing point clouds, graphs, and meshes. Moreover, I outline a vision for how topological concepts could be used in the future, comprising (1) the learning of functions on topological spaces, (2) the building of hybrid models that imbue neural networks with knowledge about the topological information in data, and (3) the analysis of qualitative properties of neural networks. With current research already addressing some of these aspects, this article thus serves as an introduction and invitation to this nascent area of research.},
+  archiveprefix = {arXiv},
+  copyright     = {arXiv.org perpetual, non-exclusive license},
+  doi           = {10.48550/ARXIV.2410.17760},
+  eprint        = {2410.17760},
+  file          = {:Rieck2024 - Topology Meets Machine Learning_ an Introduction Using the Euler Characteristic Transform.pdf:PDF:http\://arxiv.org/pdf/2410.17760v1;:TOREVIEW/Notices/241007-Rieck-v1.pdf:PDF},
+  keywords      = {Machine Learning (cs.LG), Algebraic Topology (math.AT), FOS: Computer and information sciences, FOS: Mathematics, 55N31, 62R40, 68T09},
+  primaryclass  = {cs.LG},
+  publisher     = {arXiv}
+}