Changelog

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

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[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

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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

[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 Contributing to MedTDA for more details.

External Links

• GitHub Releases

• PyPI Release History

• Release Notes (detailed)

Acknowledgments

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

See the Contributors page for a complete list.

See Also

• Installation - Installation instructions

• Contributing to MedTDA - How to contribute

• Frequently Asked Questions - Frequently asked questions