# spatial-tda
[](https://pypi.python.org/pypi/spatial-tda)
[](https://anaconda.org/conda-forge/spatial-tda)
[](https://raw.githubusercontent.com/hashansl/spatial-tda/main/docs/assets/logo.png)
**A Python package for Topological Data Analysis(TDA) in spatial data.**
- GitHub repo: <https://github.com/hashansl/spatial-tda>
- Documentation: <https://hashansl.github.io/spatial-tda/>
- PyPI: <https://pypi.org/project/spatial-tda>
- Free software: [MIT license](https://opensource.org/licenses/MIT)
## Introduction
**Spatial-TDA** is a Python package designed for extracting topological information from spatial data with minimal coding. It provides an intuitive framework for applying **topological data analysis (TDA)** to geospatial datasets, enabling researchers and analysts to explore **spatial connectivity, adjacency relationships, and persistent homology** efficiently. Built on GeoPandas, Gudhi, and Matplotlib, the package integrates seamless workflows for adjacency detection, simplicial complex construction, and persistent homology computation while maintaining geospatial integrity. With automatic adjacency extraction, **Adjacency simplicial complex formation(Filtering up/ Filtering down)**, and topological visualization tools, **Spatial-TDA** simplifies geospatial TDA workflows, making it ideal for applications in epidemiology, environmental studies and spatial network analysis. Through a combination of computational efficiency and easy-to-use functions, **Spatial-TDA** bridges the gap between geospatial analytics and topological insights, enabling users to quantify and visualize higher-order spatial structures** with just a few lines of code.
## Usage
Launch the interactive notebook tutorial for the **spatial-tda** Python package with Google Colab:(upcoming)
## Key Features
The **AdjacencySimplex** class and the **compute_persistence** function provide a comprehensive framework for processing geospatial data, constructing simplicial complexes, and performing topological data analysis (TDA). These functionalities enable the study of spatial structures and relationships with a focus on **spatial adjacency, simplicial complexes, and persistent homology**. The key features include:
### **Geospatial Data Processing and Filtering**
- **Threshold-based filtering:** Users can define minimum and maximum thresholds to focus on specific data ranges.
- **Geospatial integrity maintenance:** The framework ensures that processed data retains its geometric properties and CRS for further spatial analysis.
### **Adjacency Computation and Simplicial Complex Construction**
- **Computing adjacency relationships:** The class currently uses the Queen contiguity method to define adjacency, where regions are considered neighbors if they share at least one vertex. However, support for additional adjacency methods will be added soon, providing greater flexibility for geospatial topological analysis.
- **Generating simplicial complexes:** The class constructs **Adjacency simplicial complexes** using adjacency relationships for both **filtering up and filtering down methods**, enabling higher-order topological analysis with greater flexibility and precision.
### **Persistent Homology and Topological Summaries**
- **Computing persistence diagrams:** The **compute_persistence** function constructs a Simplex Tree using **Gudhi**, assigning filtration values based on the input variable.
- **Topological summaries (TDA metrics):** The function computes essential TDA summaries for dimension zero, including:
- **Total Lifespan (TL):** The sum of persistence intervals.
- **Average Lifespan (AL):** The mean lifespan of connected components.
- **Total Mid-Lifespan (TML):** The sum of midpoints of persistence intervals.
- **Average Mid-Lifespan (AML):** The average of midpoints of persistence intervals.
### **Efficient Computational Design**
- **Optimized spatial computations:** The class efficiently processes adjacency relationships, even for large datasets.
- **Integration with Pandas, GeoPandas, and Gudhi:** The framework seamlessly works with popular Python libraries for geospatial and topological data analysis.
- **Dynamic variable selection:** Users can select any **numerical attribute** to control filtering and sorting.
These features make the AdjacencySimplex class and **compute_persistence** function powerful tools for geospatial topological data analysis, helping researchers explore spatial connectivity, adjacency structures, and persistent homology in geospatial datasets. Whether for epidemiology, environmental studies, urban planning, or regional connectivity analysis, this framework provides an intuitive and structured approach to **spatial TDA**.
## Citations
If you find **spatial-tda** useful in your research, please consider citing the following paper(still working on) to support my work. Thank you for your support.
Raw data
{
"_id": null,
"home_page": null,
"name": "spatial-tda",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "spatial-tda",
"author": null,
"author_email": "Hashan Fernando <hashan.dan@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/1d/69/2d263eec363fea1af5d3e4a2375238896f8d37403aaf7e78e779a3e31c8d/spatial_tda-0.1.9.tar.gz",
"platform": null,
"description": "# spatial-tda\n\n\n[](https://pypi.python.org/pypi/spatial-tda)\n[](https://anaconda.org/conda-forge/spatial-tda)\n\n[](https://raw.githubusercontent.com/hashansl/spatial-tda/main/docs/assets/logo.png)\n\n**A Python package for Topological Data Analysis(TDA) in spatial data.**\n\n- GitHub repo: <https://github.com/hashansl/spatial-tda>\n- Documentation: <https://hashansl.github.io/spatial-tda/>\n- PyPI: <https://pypi.org/project/spatial-tda>\n- Free software: [MIT license](https://opensource.org/licenses/MIT)\n\n\n## Introduction\n\n**Spatial-TDA** is a Python package designed for extracting topological information from spatial data with minimal coding. It provides an intuitive framework for applying **topological data analysis (TDA)** to geospatial datasets, enabling researchers and analysts to explore **spatial connectivity, adjacency relationships, and persistent homology** efficiently. Built on GeoPandas, Gudhi, and Matplotlib, the package integrates seamless workflows for adjacency detection, simplicial complex construction, and persistent homology computation while maintaining geospatial integrity. With automatic adjacency extraction, **Adjacency simplicial complex formation(Filtering up/ Filtering down)**, and topological visualization tools, **Spatial-TDA** simplifies geospatial TDA workflows, making it ideal for applications in epidemiology, environmental studies and spatial network analysis. Through a combination of computational efficiency and easy-to-use functions, **Spatial-TDA** bridges the gap between geospatial analytics and topological insights, enabling users to quantify and visualize higher-order spatial structures** with just a few lines of code.\n\n## Usage\n\nLaunch the interactive notebook tutorial for the **spatial-tda** Python package with Google Colab:(upcoming)\n\n## Key Features \n\nThe **AdjacencySimplex** class and the **compute_persistence** function provide a comprehensive framework for processing geospatial data, constructing simplicial complexes, and performing topological data analysis (TDA). These functionalities enable the study of spatial structures and relationships with a focus on **spatial adjacency, simplicial complexes, and persistent homology**. The key features include: \n\n### **Geospatial Data Processing and Filtering**\n- **Threshold-based filtering:** Users can define minimum and maximum thresholds to focus on specific data ranges. \n- **Geospatial integrity maintenance:** The framework ensures that processed data retains its geometric properties and CRS for further spatial analysis. \n\n### **Adjacency Computation and Simplicial Complex Construction**\n- **Computing adjacency relationships:** The class currently uses the Queen contiguity method to define adjacency, where regions are considered neighbors if they share at least one vertex. However, support for additional adjacency methods will be added soon, providing greater flexibility for geospatial topological analysis.\n- **Generating simplicial complexes:** The class constructs **Adjacency simplicial complexes** using adjacency relationships for both **filtering up and filtering down methods**, enabling higher-order topological analysis with greater flexibility and precision.\n\n### **Persistent Homology and Topological Summaries**\n- **Computing persistence diagrams:** The **compute_persistence** function constructs a Simplex Tree using **Gudhi**, assigning filtration values based on the input variable.\n- **Topological summaries (TDA metrics):** The function computes essential TDA summaries for dimension zero, including: \n - **Total Lifespan (TL):** The sum of persistence intervals. \n - **Average Lifespan (AL):** The mean lifespan of connected components. \n - **Total Mid-Lifespan (TML):** The sum of midpoints of persistence intervals. \n - **Average Mid-Lifespan (AML):** The average of midpoints of persistence intervals. \n\n### **Efficient Computational Design**\n- **Optimized spatial computations:** The class efficiently processes adjacency relationships, even for large datasets. \n- **Integration with Pandas, GeoPandas, and Gudhi:** The framework seamlessly works with popular Python libraries for geospatial and topological data analysis. \n- **Dynamic variable selection:** Users can select any **numerical attribute** to control filtering and sorting. \n\nThese features make the AdjacencySimplex class and **compute_persistence** function powerful tools for geospatial topological data analysis, helping researchers explore spatial connectivity, adjacency structures, and persistent homology in geospatial datasets. Whether for epidemiology, environmental studies, urban planning, or regional connectivity analysis, this framework provides an intuitive and structured approach to **spatial TDA**.\n\n## Citations\n\nIf you find **spatial-tda** useful in your research, please consider citing the following paper(still working on) to support my work. Thank you for your support.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A Python package for Topological Data Analysis(TDA) in spatial data.",
"version": "0.1.9",
"project_urls": {
"Homepage": "https://github.com/hashansl/spatial-tda"
},
"split_keywords": [
"spatial-tda"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d15a596ab24656feaacea2b84ee3b7647d3ada276be638022c849509366ae3f8",
"md5": "5e6bc08af62ff83263f5812cc908659f",
"sha256": "3078a443382dca13e345e977428de2f0bc9a52eef1e48b23d3f3ec4711266e05"
},
"downloads": -1,
"filename": "spatial_tda-0.1.9-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "5e6bc08af62ff83263f5812cc908659f",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.8",
"size": 10115,
"upload_time": "2025-02-16T22:33:14",
"upload_time_iso_8601": "2025-02-16T22:33:14.698225Z",
"url": "https://files.pythonhosted.org/packages/d1/5a/596ab24656feaacea2b84ee3b7647d3ada276be638022c849509366ae3f8/spatial_tda-0.1.9-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1d692d263eec363fea1af5d3e4a2375238896f8d37403aaf7e78e779a3e31c8d",
"md5": "3b9d2e2a4fdbf71c503fa46b89adf0c7",
"sha256": "7e787497361b90f845eafa7f6a52bf9ac82e6e65b79af2be681be229f9b93b1b"
},
"downloads": -1,
"filename": "spatial_tda-0.1.9.tar.gz",
"has_sig": false,
"md5_digest": "3b9d2e2a4fdbf71c503fa46b89adf0c7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 12410081,
"upload_time": "2025-02-16T22:33:16",
"upload_time_iso_8601": "2025-02-16T22:33:16.601803Z",
"url": "https://files.pythonhosted.org/packages/1d/69/2d263eec363fea1af5d3e4a2375238896f8d37403aaf7e78e779a3e31c8d/spatial_tda-0.1.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-16 22:33:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hashansl",
"github_project": "spatial-tda",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": []
},
{
"name": "geopandas",
"specs": []
},
{
"name": "pandas",
"specs": []
},
{
"name": "gudhi",
"specs": []
},
{
"name": "Pillow",
"specs": []
},
{
"name": "matplotlib",
"specs": []
}
],
"lcname": "spatial-tda"
}
JSON
