BaSaBu/TDA-Viz

TDA Cycle Explorer

TDA Cycle Explorer is an interactive web app for exploring one-dimensional persistent-homology features in networks. It connects points in a persistence diagram to the cycles, nodes, edges, and triangles that produced them.

[Open the deployed app on Hugging Face Spaces](https://huggingface.co/spaces/BaSaBu/TDA-Viz)

What you can do

• —Browse cycles in a persistence diagram or barcode.
• —Filter cycles by lifespan, size, node, edge, or status.
• —Inspect a selected cycle in an interactive 3D view.
• —Use a timeline to watch the cycle form and close.
• —See where a cycle appears in the full network.
• —Compare several cycles and export images.

Try it online

Open the Hugging Face Space. For input requirements and instructions for each feature, read the User Guide.

Run locally

Local use requires Python 3.11 or newer. The included scripts create a virtual environment, install the Python packages, start the app, and open it at http://localhost:8000.

Windows

Run these files from the project folder:

1. 1.install.bat — one-time setup
2. 2.start.bat — start the app

macOS or Linux

bash install.sh   # one-time setup
bash start.sh     # start the app

Press Ctrl+C in the terminal to stop the local server. When you run the app locally, uploaded data stays on your computer.

Development

Run the backend from the backend folder:

python -m venv venv

# Windows
venv\Scripts\activate

# macOS or Linux
# source venv/bin/activate

pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

In a second terminal, run the frontend:

cd frontend
npm install
npm run dev

The development frontend runs at http://localhost:5173 and connects to the backend at port 8000.

After changing frontend code, rebuild the committed production bundle:

cd frontend
npm run build

Run backend tests with:

cd backend
python -m pytest -q

Project structure

backend/    FastAPI API, data parsing, layouts, and tests
frontend/   React and Vite user interface
Dockerfile  Hugging Face Spaces deployment

The main technologies are FastAPI, React, Vite, ECharts, Three.js, NetworkX, and igraph.

Documentation

• —User Guide — how to prepare data and use the web app
• —Architecture — code structure, data flow, algorithms, API, and state.