.. _api_reference:

=============
API Reference
=============

This section provides detailed API documentation for all MedTDA modules and classes.

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

Overview
========

MedTDA is organized into several key modules:

* **featureextractor** - Main interface for TDA feature extraction
* **preprocessor** - Image preprocessing utilities
* **ph_computer** - Persistent homology computation
* **barcodeextractor** - Raw barcode extraction
* **vectorizers** - Methods to convert barcodes to feature vectors
* **loaders** - Image and mask loading/saving
* **utils** - General utility functions
* **cli** - Command-line interface

Quick Navigation
================

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Module
     - Description
   * - :doc:`featureextractor`
     - Main FeatureExtractor class for end-to-end feature extraction
   * - :doc:`preprocessor`
     - Preprocessor class for image normalization and preparation
   * - :doc:`ph_computer`
     - Functions for computing persistent homology
   * - :doc:`barcodeextractor`
     - BarcodeExtractor class for raw barcode computation
   * - :doc:`vectorizers`
     - All 8 vectorization methods (functions)
   * - :doc:`loaders`
     - Image and mask loading/saving functions
   * - :doc:`utils`
     - General utility functions for image processing
   * - :doc:`cli`
     - Command-line interface functions and argument parsing

Typical Usage Pattern
======================

The typical workflow uses the **FeatureExtractor** class as the main interface::

    from medtda import FeatureExtractor

    # Initialize with configuration
    extractor = FeatureExtractor(
        vectorization_method='PersImage',
        normalize=True
    )

    # Extract features
    features = extractor.execute('image.nii.gz', mask='mask.nii.gz')

For more control, you can use individual components::

    from medtda import Preprocessor, BarcodeExtractor
    from medtda.vectorizers import persistence_image

    # Step-by-step processing
    preprocessor = Preprocessor(normalize=True)
    processed_image, _ = preprocessor.preprocess(image, mask)

    extractor = BarcodeExtractor()
    barcodes = extractor.execute(processed_image)

    features = persistence_image(barcodes['H1'])

Module Documentation
====================

.. toctree::
   :maxdepth: 2

   featureextractor
   preprocessor
   ph_computer
   barcodeextractor
   vectorizers
   loaders
   utils
   cli

Core Classes
============

FeatureExtractor
----------------

The main interface for TDA feature extraction. See :doc:`featureextractor` for details.

Key methods:

* ``execute(image, mask=None)`` - Extract features from an image
* ``set_vectorization_method(method, **params)`` - Change vectorization method
* ``enable_vectorization_methods(methods)`` - Enable multiple methods

Preprocessor
------------

Handles image preprocessing operations. See :doc:`preprocessor` for details.

Key methods:

* ``preprocess(image, mask=None)`` - Apply all preprocessing steps
* Individual methods for normalization, resampling, windowing, etc.

BarcodeExtractor
----------------

Extracts raw persistence barcodes. See :doc:`barcodeextractor` for details.

Key methods:

* ``extract(image)`` - Compute persistence barcodes
* ``set_filtration_type(filtration_type)`` - Change filtration type
* ``set_construction(construction)`` - Change construction method

Vectorization Functions
========================

MedTDA provides 8 different vectorization methods as standalone functions:

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Function
     - Description
   * - ``persistence_stats(barcode)``
     - Statistical summaries (mean, std, min, max, etc.)
   * - ``betti_curve(barcode, resolution)``
     - Betti numbers as function of filtration value
   * - ``persistence_image(barcode, bandwidth, resolution)``
     - 2D histogram weighted by persistence
   * - ``persistence_landscape(barcode, resolution, num_landscapes)``
     - Functional representation using landscapes
   * - ``persistence_silhouette(barcode, resolution, weight)``
     - Average persistence landscape
   * - ``entropy_summary(barcode, resolution)``
     - Information-theoretic features
   * - ``persistence_lifespan(barcode, resolution)``
     - Distribution of feature lifespans
   * - ``persistence_tropical_coordinates(barcode, r)``
     - Tropical algebra representation

See :doc:`vectorizers` for detailed documentation of each method.

Utility Functions
=================

The ``utils`` module provides various helper functions:

* ``resample_image()`` - Image resampling
* ``normalize_image()`` - Intensity normalization
* ``apply_mask()`` - Apply binary mask
* ``crop_to_roi()`` - Crop to region of interest
* ``extract_label_from_mask()`` - Extract single label from multi-label mask

See :doc:`utils` for complete documentation.

Image Loading and Saving
=========================

The ``loaders`` module handles I/O operations:

* ``load_image(path)`` - Load 2D or 3D images (NIFTI, PNG, TIFF, etc.)
* ``load_mask(path)`` - Load binary or multi-label masks
* ``save_image(array, path)`` - Save images to disk
* Validation functions for images and masks

See :doc:`loaders` for complete documentation.

Command-Line Interface
======================

The ``cli`` module provides the command-line interface:

* ``create_parser()`` - Create argument parser
* ``process_single_file(args)`` - Process single image
* ``process_batch(args)`` - Process batch of images
* ``main()`` - Main entry point

See :doc:`cli` for complete documentation.

Indices and Tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`