.. _changelog:

=========
Changelog
=========

All notable changes to MedTDA will be documented in this file.

The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.0.0/>`_,
and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`_.

.. contents:: Versions
   :local:
   :depth: 1

[Unreleased]
============

Features planned for future releases:

- GPU acceleration for persistent homology computation
- Additional vectorization methods (Euler characteristic curves, Wasserstein distances)
- Support for time-series medical imaging (4D data)
- Integration with deep learning frameworks (PyTorch, TensorFlow)
- Interactive visualization dashboard
- Cloud processing support
- Additional file format support (MINC, MGH)

[1.0.0] - 2024-01-15
====================

**First stable release!**

This is the first production-ready version of MedTDA with comprehensive features for topological data analysis of medical images.

Added
-----

Core Features
~~~~~~~~~~~~~

- **FeatureExtractor**: High-level API for end-to-end feature extraction
- **Preprocessor**: Comprehensive medical image preprocessing
- **PersistentHomologyComputer**: Compute persistent homology from images
- **BarcodeExtractor**: Extract and analyze persistence barcodes
- Multiple vectorization methods implemented

Vectorization Methods
~~~~~~~~~~~~~~~~~~~~~

- Persistence statistics (mean, std, percentiles)
- Betti curves
- Persistence images
- Persistence landscapes
- Persistence entropy
- Silhouette representation

File Format Support
~~~~~~~~~~~~~~~~~~~

- NIFTI (.nii, .nii.gz)
- DICOM (.dcm)
- NRRD (.nrrd, .nhdr)
- PNG, TIFF, JPEG (2D images)
- NumPy arrays

Preprocessing
~~~~~~~~~~~~~

- Multiple normalization methods (minmax, zscore, robust)
- Isotropic and anisotropic resampling
- ROI cropping with padding
- Intensity windowing (for CT)
- Multi-label mask support

Command-Line Interface
~~~~~~~~~~~~~~~~~~~~~~

- ``medtda extract`` - Single image feature extraction
- ``medtda batch`` - Batch processing
- Configuration file support (YAML)
- Multiple output formats (NumPy, CSV, JSON, HDF5)

Visualization
~~~~~~~~~~~~~

- Persistence barcode plots
- Persistence diagram plots
- Betti curve plots
- Customizable plotting styles

Documentation
~~~~~~~~~~~~~

- Complete Sphinx documentation
- Quickstart tutorial
- Comprehensive user guide
- API reference
- Theory background
- Multiple examples
- Interactive Jupyter notebook tutorial
- FAQ and troubleshooting

Changed
-------

- N/A (first release)

Deprecated
----------

- N/A (first release)

Removed
-------

- N/A (first release)

Fixed
-----

- N/A (first release)

Security
--------

- N/A (first release)

[0.3.0] - 2023-11-20
====================

**Beta release with improved API**

Added
-----

- FeatureExtractor class for simplified workflow
- Configuration file support
- Batch processing utilities
- Progress tracking with tqdm
- Multi-label mask support
- Additional vectorization methods (silhouette)

Changed
-------

- Refactored API for better usability
- Improved error messages
- Unified parameter naming conventions
- Better default parameters

Fixed
-----

- Memory leak in batch processing
- DICOM orientation handling
- Edge cases in ROI cropping
- Normalization numerical stability

[0.2.0] - 2023-09-10
====================

**Alpha release with core functionality**

Added
-----

- Basic persistent homology computation
- Sublevel and superlevel filtrations
- Persistence statistics vectorization
- Betti curves
- Persistence images
- NIFTI file loader
- Basic preprocessing (normalization, resampling)
- Command-line interface (basic)

Changed
-------

- Switched from Ripser to GUDHI for better performance
- Improved memory efficiency

Fixed
-----

- Spacing metadata handling
- Empty barcode edge cases

[0.1.0] - 2023-07-01
====================

**Initial prototype release**

Added
-----

- Proof-of-concept implementation
- Basic persistent homology on 3D images
- Simple persistence statistics
- NIFTI support
- Basic documentation

Known Issues
------------

- Limited to small images (< 128³)
- No batch processing
- Minimal documentation
- Limited testing

---

Version History Summary
=======================

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

   * - Version
     - Date
     - Highlights
   * - 1.0.0
     - 2024-01-15
     - First stable release with comprehensive features
   * - 0.3.0
     - 2023-11-20
     - Beta release with improved API
   * - 0.2.0
     - 2023-09-10
     - Alpha release with core functionality
   * - 0.1.0
     - 2023-07-01
     - Initial prototype

Migration Guides
================

Migrating from 0.3.x to 1.0.0
-----------------------------

**API Changes:**

Most of the API is backward compatible. Main changes:

**1. Imports:**

.. code-block:: python

    # Old (0.3.x)
    from medtda.extractors import FeatureExtractor
    from medtda.preprocessing import Preprocessor
    
    # New (1.0.0)
    from medtda import FeatureExtractor, Preprocessor

**2. Parameter names standardized:**

.. code-block:: python

    # Old
    extractor = FeatureExtractor(
        normalize_type='robust',  # Old name
        max_dim=2,                  # Old name
        vectorizer='pi'             # Old name
    )
    
    # New
    extractor = FeatureExtractor(
        normalize_method='robust',      # Standardized
        max_dimension=2,                # Standardized
        vectorization_method='PersImage'  # Standardized
    )

**3. Return values:**

.. code-block:: python

    # Old - returns dict or array depending on single/multiple methods
    features = extractor.execute(image)
    
    # New - always returns dict for consistency
    features = extractor.execute(image)
    stats = features['PersStats_H0_mean']  # Access specific feature by key

**4. CLI changes:**

.. code-block:: bash

    # Old
    medtda process image.nii.gz --output features.npy
    
    # New
    medtda extract image.nii.gz --output features.npy

**Deprecated features:**

- ``FeatureExtractor.process()`` → use ``FeatureExtractor.execute()``
- ``normalize_type`` parameter → use ``normalize_method``
- ``max_dim`` parameter → use ``max_dimension``

Migrating from 0.2.x to 0.3.x
-----------------------------

**Major refactoring in 0.3.0 introduced breaking changes:**

**1. New class structure:**

.. code-block:: python

    # Old (0.2.x) - function-based
    from medtda import compute_persistence, vectorize_barcodes
    
    barcodes = compute_persistence(image)
    features = vectorize_barcodes(barcodes, method='stats')
    
    # New (0.3.x) - class-based
    from medtda import FeatureExtractor
    
    extractor = FeatureExtractor()
    features = extractor.execute(image)

**2. Configuration:**

.. code-block:: python

    # Old - everything as function arguments
    barcodes = compute_persistence(
        image, 
        filtration='sublevel',
        max_dim=2,
        normalize=True,
        spacing=(1, 1, 1)
    )
    
    # New - create extractor with config
    extractor = FeatureExtractor(
        filtration_type='sublevel',
        max_dimension=2,
        normalize=True,
        spacing=(1, 1, 1)
    )
    features = extractor.execute(image)

Migrating from 0.1.x to 0.2.x
-----------------------------

0.2.0 was a major rewrite with different API. Recommend upgrading directly to 1.0.0.

Release Cycle
=============

MedTDA follows semantic versioning:

- **Major versions (X.0.0):** Breaking API changes
- **Minor versions (1.X.0):** New features, backward compatible
- **Patch versions (1.0.X):** Bug fixes, backward compatible

**Release frequency:**

- **Major:** ~1-2 years
- **Minor:** ~3-6 months
- **Patch:** As needed for critical bugs

**Support:**

- **Latest major version:** Full support
- **Previous major version:** Security fixes for 1 year
- **Older versions:** Community support only

Deprecation Policy
==================

When features are deprecated:

1. **Announced** in release notes
2. **Warning** added to code (runtime DeprecationWarning)
3. **Maintained** for at least one minor version
4. **Removed** in next major version

**Example timeline:**

- v1.1.0: Feature X deprecated, warning added
- v1.2.0: Feature X still works, warning remains
- v2.0.0: Feature X removed

Contributing to Changelog
==========================

When contributing code, please update this changelog:

**Format:**

.. code-block:: markdown

    [Unreleased]
    ============
    
    Added
    -----
    - New feature description (#123)
    
    Fixed
    -----
    - Bug fix description (#124)

**Categories:**

- **Added:** New features
- **Changed:** Changes in existing functionality
- **Deprecated:** Soon-to-be removed features
- **Removed:** Removed features
- **Fixed:** Bug fixes
- **Security:** Security fixes

See :doc:`contributing` for more details.

External Links
==============

- `GitHub Releases <https://github.com/dashtiali/medtda/releases>`_
- `PyPI Release History <https://pypi.org/project/medtda/#history>`_
- `Release Notes (detailed) <https://github.com/dashtiali/medtda/blob/main/CHANGELOG.md>`_

Acknowledgments
===============

Each release acknowledges contributors. Thank you to everyone who has contributed to MedTDA!

See the `Contributors page <https://github.com/dashtiali/medtda/graphs/contributors>`_ for a complete list.

See Also
========

- :doc:`installation` - Installation instructions
- :doc:`contributing` - How to contribute
- :doc:`faq` - Frequently asked questions
