Skip to content

Installation Guide

⚠️ Planned Feature: The [api] extra (FastAPI/Uvicorn) and MLflow experiment tracking listed below are optional dependencies for features not yet implemented in the current release.

This guide covers all installation methods for ga-optimized-trees.

Quick Start

# Minimal installation (core dependencies only)
pip install -e .

# Or with all features
pip install -e .[all]

Installation Methods

For development or if you want to modify the code:

# Clone repository
git clone https://github.com/ibrah5em/ga-optimized-trees.git
cd ga-optimized-trees

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in editable mode
pip install -e .

2. User Installation (From Source)

git clone https://github.com/ibrah5em/ga-optimized-trees.git
cd ga-optimized-trees
pip install .

3. From PyPI (When Published)

# Not yet available - coming soon!
# pip install ga-optimized-trees

Optional Dependencies

The package has several optional dependency groups:

Visualization (viz)

For tree visualization with Graphviz:

pip install -e .[viz]

# System dependencies (required for graphviz):
# Ubuntu/Debian:
sudo apt-get install graphviz

# macOS:
brew install graphviz

# Windows: Download from https://graphviz.org/download/

Optimization (optimization)

For hyperparameter tuning and experiment tracking:

pip install -e .[optimization]

Includes:

  • Optuna (Bayesian optimization)
  • MLflow (experiment tracking)

Baseline Models (baselines)

For comparing against ensemble methods:

pip install -e .[baselines]

Includes:

  • XGBoost
  • LightGBM

Explainability (explainability)

For model interpretation tools:

pip install -e .[explainability]

Includes:

  • SHAP
  • LIME

API Support (api)

For building web interfaces:

pip install -e .[api]

Includes:

  • FastAPI
  • Uvicorn
  • Pydantic

All Optional Dependencies

Install everything at once:

pip install -e .[all]

Development Setup

For contributors:

# Install with development dependencies
pip install -e .[dev]

# Install pre-commit hooks
pre-commit install

# Run tests
pytest tests/ -v

# Check code quality
black src/ tests/ scripts/
isort src/ tests/ scripts/
flake8 src/ tests/ scripts/
mypy src/

Complete Setup (Everything)

For the full experience with all features:

pip install -e .[full]

This includes:

  • Core dependencies
  • All optional features (viz, optimization, baselines, explainability, api)
  • Development tools (testing, linting, formatting)
  • Documentation tools

Requirements Files

Alternative installation using requirements files:

# Core only
pip install -r requirements.txt

# With optional dependencies
pip install -r requirements.txt
pip install -r requirements-optional.txt

# Development setup
pip install -r requirements-dev.txt

Verification

Test your installation:

# Import check
python -c "import ga_trees; print('✓ Installation successful!')"

# Run quick test
python scripts/train.py --dataset iris --generations 5 --population 10

# Run test suite
pytest tests/unit/ -v

Troubleshooting

Issue: "No module named 'ga_trees'"

Solution:

# Make sure you installed in editable mode
pip install -e .

# Or add src to PYTHONPATH
export PYTHONPATH="${PYTHONPATH}:$(pwd)/src"

Issue: Graphviz not found

Solution:

# Install system package first, then Python package
# Ubuntu/Debian:
sudo apt-get install graphviz
pip install graphviz

# macOS:
brew install graphviz
pip install graphviz

Issue: NumPy version conflict

Solution:

# Clean install
pip uninstall numpy
pip install "numpy>=1.24.0,<2.0.0"

Issue: DEAP import error

Solution:

pip install deap>=1.4.1

Platform-Specific Notes

Windows

# Use Anaconda for easier setup
conda create -n ga-trees python=3.11
conda activate ga-trees
pip install -e .

macOS (Apple Silicon)

# Use native ARM build
pip install -e .

# If issues with numpy/scipy, use conda:
conda install numpy scipy
pip install -e . --no-deps

Linux

# Install system dependencies
sudo apt-get update
sudo apt-get install python3-dev build-essential

# Then install package
pip install -e .

Docker Installation

# Build image
docker build -t ga-trees:latest .

# Run container
docker run --rm ga-trees:latest python scripts/train.py --dataset iris

# With mounted volumes
docker run --rm \
  -v $(pwd)/results:/app/results \
  -v $(pwd)/models:/app/models \
  ga-trees:latest \
  python scripts/train.py --dataset breast_cancer

Upgrading

# Pull latest changes
git pull origin main

# Reinstall
pip install -e . --upgrade

Uninstalling

# Remove package
pip uninstall ga-optimized-trees

# Remove virtual environment
deactivate
rm -rf venv/

# Clean build artifacts
rm -rf build/ dist/ *.egg-info/

Next Steps

After installation:

  1. Quick Tutorial: See docs/getting-started/quickstart.md
  2. Run Examples: Try python scripts/train.py --dataset iris
  3. Read Docs: Check docs/README.md
  4. Run Tests: pytest tests/ -v

Support

If you encounter issues:

  1. Check Troubleshooting Guide
  2. Search GitHub Issues
  3. Open a new issue with:
  4. Python version: python --version
  5. OS and version
  6. Full error traceback
  7. Installation method used