============
Installation
============

MedTDA can be installed via pip or from source. This guide covers all installation methods and common troubleshooting steps.

Install from PyPI
=================

The simplest way to install MedTDA is using pip:

.. code-block:: bash

   pip install medtda

This will install MedTDA and its core dependencies.

Requirements
============

**Python Version**

MedTDA requires Python 3.8 or later. Check your Python version:

.. code-block:: bash

   python --version

**Core Dependencies**

The following packages are automatically installed with Med-TDA:

* **NumPy** (≥1.21.0) - Numerical computing and array operations
* **SciPy** (≥1.7.0) - Scientific computing and optimization
* **GUDHI** (≥3.5.0) - Persistent homology computation
* **cripser** (≥0.0.32) - Fast cubical complex persistence
* **SimpleITK** (≥2.1.0) - Medical image I/O and processing (NIfTI, NRRD, MHA, MHD)
* **Pillow** (≥9.0.0) - 2D image I/O (PNG, JPG, TIFF)
* **scikit-image** (≥0.19.0) - Image processing algorithms
* **scikit-learn** (≥1.0.0) - Machine learning utilities and preprocessing
* **pandas** (≥1.3.0) - Data manipulation and CSV handling
* **matplotlib** (≥3.5.0) - Plotting and visualization
* **seaborn** (≥0.11.0) - Statistical data visualization
* **PyYAML** (≥6.0) - Configuration file support
* **tqdm** (≥4.60.0) - Progress bars for CLI

All of these dependencies will be installed automatically when you install Med-TDA via pip.

Install from Source
===================

For the latest development version or to contribute to Med-TDA:

.. code-block:: bash

   # Clone the repository
   git clone https://github.com/dashtiali/medtda.git
   cd medtda
   
   # Install in development mode
   pip install -e .

Development Installation
========================

If you plan to contribute or run tests:

.. code-block:: bash

   # Clone repository
   git clone https://github.com/dashtiali/medtda.git
   cd medtda
   
   # Install in development mode with dev dependencies
   pip install -e .[dev]

This installs additional packages for testing and documentation:

* pytest
* pytest-cov
* sphinx
* sphinx-rtd-theme
* nbsphinx

Verify Installation
===================

Check that MedTDA is installed correctly:

.. code-block:: python

   import medtda
   print(medtda.__version__)

Run a quick test:

.. code-block:: python

   from medtda import FeatureExtractor
   import numpy as np
   
   # Create a simple test image
   image = np.random.rand(50, 50)
   
   # Initialize extractor
   extractor = FeatureExtractor(vectorization_method='PersStats')
   
   # Extract features (should run without errors)
   features = extractor.execute(image)
   print(f"Successfully extracted {len(features)} features")

Troubleshooting
===============

Common Issues
-------------

**ImportError: No module named 'medtda'**

Solution: Make sure pip installation completed successfully and you're using the correct Python environment.

.. code-block:: bash

   # Check if medtda is installed
   pip list | grep medtda
   
   # Reinstall if necessary
   pip install --upgrade medtda

**ImportError: No module named 'SimpleITK'**

Solution: Install SimpleITK for 3D/4D medical image support:

.. code-block:: bash

   pip install SimpleITK

**GUDHI or cripser installation fails**

Solution: These packages may require compilation. Try:

.. code-block:: bash

   # Install from conda-forge (if using conda)
   conda install -c conda-forge gudhi
   
   # Or upgrade pip and try again
   pip install --upgrade pip
   pip install gudhi cripser

**Memory errors during installation**

Solution: Install packages individually if you have limited RAM:

.. code-block:: bash

   pip install numpy
   pip install gudhi
   pip install cripser
   pip install scikit-learn
   pip install medtda --no-deps
   pip install medtda  # Install remaining dependencies

Platform-Specific Notes
-----------------------

**Windows**

* Use Anaconda/Miniconda for easier dependency management
* Visual C++ build tools may be required for some dependencies

**macOS** 

* Xcode Command Line Tools may be required:

  .. code-block:: bash

     xcode-select --install

**Linux**

* GCC compiler required for some dependencies
* Ubuntu/Debian:

  .. code-block:: bash

     sudo apt-get update
     sudo apt-get install build-essential python3-dev

* CentOS/RHEL:

  .. code-block:: bash

     sudo yum groupinstall "Development Tools"
     sudo yum install python3-devel

Virtual Environments
====================

It's recommended to use a virtual environment:

**Using venv**

.. code-block:: bash

   # Create virtual environment
   python -m venv medtda-env
   
   # Activate (Linux/macOS)
   source medtda-env/bin/activate
   
   # Activate (Windows)
   medtda-env\Scripts\activate
   
   # Install MedTDA
   pip install medtda

**Using conda**

.. code-block:: bash

   # Create conda environment
   conda create -n medtda python=3.10
   conda activate medtda
   
   # Install dependencies from conda-forge
   conda install -c conda-forge numpy gudhi scikit-learn pyyaml tqdm
   
   # Install MedTDA
   pip install medtda

Updating MedTDA
===============

To update to the latest version:

.. code-block:: bash

   pip install --upgrade medtda

To update to a specific version:

.. code-block:: bash

   pip install medtda==0.2.0

Uninstallation
==============

To remove MedTDA:

.. code-block:: bash

   pip uninstall medtda

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

- :doc:`quickstart` - Get started with a 5-minute tutorial
- :doc:`user_guide` - Learn about all features and capabilities
- :doc:`api/index` - Explore the API documentation
