.. _theory:

==========
TDA Theory
==========

This section provides background on Topological Data Analysis (TDA) concepts used in MedTDA.

.. note::
   This section provides conceptual overviews and intuitive explanations.
   For rigorous mathematical treatment, see the :doc:`../references` page.

.. contents:: Contents
   :local:
   :depth: 2

Overview
========

**Topological Data Analysis (TDA)** is a field of mathematics that studies the shape and structure of data using techniques from algebraic topology. TDA provides tools to:

* Quantify global structure and connectivity
* Identify holes, voids, and higher-dimensional features
* Capture multi-scale geometric and topological properties
* Provide robust descriptors invariant to small perturbations

Why TDA for Medical Images?
============================

Medical images contain rich structural information that traditional methods may miss. TDA excels at:

Capturing Complex Anatomy
--------------------------

Medical structures often have intricate topological features:

* **Blood vessels:** Networks with loops and branching
* **Organs:** Cavities and internal voids
* **Tumors:** Irregular boundaries and internal structure
* **Tissue:** Porous structures and connectivity patterns

Traditional image analysis focuses on intensity values or local features, while TDA captures global topological properties.

Multi-Scale Analysis
---------------------

Diseases often manifest at different scales:

* **Microscopic:** Cell-level changes
* **Mesoscopic:** Tissue structure alterations
* **Macroscopic:** Organ-level deformations

Persistent homology naturally analyzes structures across scales through filtration.

Robustness to Noise
--------------------

TDA methods are inherently robust:

* Persistence distinguishes signal from noise
* Short-lived features (low persistence) are likely noise
* Long-lived features (high persistence) represent stable structure

Clinical Applications
----------------------

TDA has been successfully applied to:

* **Cancer detection:** Tumor microenvironment characterization
* **Neuroscience:** Brain connectivity and structure
* **Cardiology:** Vessel network analysis
* **Radiology:** Texture and structure quantification
* **Pathology:** Tissue organization patterns

Core Concepts
=============

The TDA pipeline in MedTDA follows these steps:

1. **Filtration Construction**
   
   Build a sequence of topological spaces from image intensities.
   
   See: :doc:`filtrations`

2. **Persistent Homology Computation**
   
   Track topological features (connected components, loops, voids) across the filtration.
   
   See: :doc:`persistent_homology`

3. **Barcode/Diagram Generation**
   
   Represent persistent features as barcodes or diagrams.
   
   See: :doc:`barcodes_diagrams`

4. **Vectorization**
   
   Convert variable-length barcodes to fixed-length feature vectors for machine learning.
   
   See: :doc:`vectorization_methods`

Topological Features in Medical Images
=======================================

H0: Connected Components
-------------------------

**Dimension 0 homology** counts connected regions:

* Number of separate structures
* Component sizes and distributions
* Merging patterns across scales

**Medical examples:**

* Individual cells or nuclei
* Separate lesions or tumors
* Disconnected tissue regions

H1: Loops and Holes
-------------------

**Dimension 1 homology** detects loops and tunnels:

* Circular structures
* Network connectivity
* Enclosed regions

**Medical examples:**

* Blood vessel loops
* Glandular structures
* Circular tissue arrangements
* Airway branching patterns

H2: Voids and Cavities
----------------------

**Dimension 2 homology** identifies enclosed voids (3D only):

* Internal cavities
* Hollow structures
* Enclosed volumes

**Medical examples:**

* Cysts and fluid-filled regions
* Hollow organs (stomach, bladder)
* Air-filled structures (lungs)
* Necrotic tumor cores

Mathematical Foundation
=======================

MedTDA is built on well-established results from algebraic topology:

* **Simplicial and cubical homology** — the algebraic machinery for counting topological features
* **Persistent homology** — tracking how features are born and die across a filtration
* **Persistence modules and stability** — guaranteeing that small data perturbations produce small changes in barcodes (bottleneck stability theorem)

This documentation focuses on:

* Intuitive understanding of concepts
* Practical usage in medical imaging
* Implementation details in MedTDA

For rigorous mathematical treatment, see the :doc:`../references` page.

Key Concepts Summary
====================

.. glossary::

   Filtration
      A nested sequence of topological spaces built from the image.
      
   Persistent Homology
      Tracking topological features across filtration scales.
      
   Birth Time
      Filtration value when a feature first appears.
      
   Death Time
      Filtration value when a feature disappears.
      
   Persistence
      Lifespan of a feature: death - birth.
      
   Barcode
      Visual representation of features as horizontal bars.
      
   Persistence Diagram
      Scatter plot of (birth, death) pairs.
      
   Betti Numbers
      Count of features at each dimension (β₀, β₁, β₂).

Theory Sections
===============

.. toctree::
   :maxdepth: 2

   persistent_homology
   filtrations
   barcodes_diagrams
   vectorization_methods

Further Reading
===============

Recommended Resources
---------------------

**Books:**

* Edelsbrunner & Harer - *Computational Topology: An Introduction*
* Oudot - *Persistence Theory: From Quiver Representations to Data Analysis*
* Ghrist - *Elementary Applied Topology*

**Survey Papers:**

* Carlsson - *Topology and Data* (2009)
* Edelsbrunner & Morozov - *Persistent Homology: Theory and Practice* (2012)
* Wasserman - *Topological Data Analysis* (2018)

**Medical Imaging Applications:**

* Adcock et al. - *The Ring of Algebraic Functions on Persistence Bar Codes* (2016)
* Qaiser et al. - *Persistent Homology for Fast Tumor Segmentation in Whole Slide Histology Images* (2019)
* Kaji et al. - *Efficient Persistent Homology Based on Maximal Simplices* (2020)

Next Steps
==========

After understanding the theory, see:

* :doc:`../user_guide` - Practical usage guide
* :doc:`../quickstart` - Get started quickly
* :doc:`../api/index` - Detailed API documentation
* :doc:`../examples/index` - Practical examples

See Also
========

* :doc:`../user_guide/persistent_homology` - User guide on PH computation
* :doc:`../user_guide/vectorization` - Vectorization methods guide
* :doc:`../api/ph_computer` - PH computation API
* :doc:`../api/vectorizers` - Vectorization API
