# Installation

GeoStep is a proprietary Python library for designing and analyzing geographic marketing experiments. This guide covers installation procedures and environment setup.

## Requirements

### System Requirements
- **Python**: 3.8 or higher
- **Operating System**: Windows, macOS, or Linux
- **Memory**: 4GB RAM minimum (8GB+ recommended for large datasets)
- **Storage**: 500MB for library and dependencies

### Core Dependencies
The library requires the following Python packages (automatically installed):
- `pandas>=1.3.0` - Data manipulation and analysis
- `numpy>=1.21.0` - Numerical computing
- `scipy>=1.7.0` - Statistical functions
- `statsmodels>=0.13.0` - Statistical models
- `scikit-learn>=1.0.0` - Machine learning utilities
- `matplotlib>=3.4.0` - Plotting and visualization
- `seaborn>=0.13.0` - Statistical data visualization
- `joblib>=1.0.0` - Parallel computing
- `rich>=10.0.0` - Rich terminal formatting
- `psutil>=5.8.0` - System monitoring

## Installation Methods

### Method 1: Standard Installation (Recommended)

Install GeoStep in editable mode for easy updates and modifications:

```bash
# Clone the repository
git clone https://github.com/ [your-github-org]/geostep.git
cd geostep

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

# Install in editable mode with all dependencies
pip install -e .
```

### Method 2: Developer Installation

For contributors and developers who need testing and documentation tools:

```bash
# Clone and enter directory
git clone https://github.com/ [your-github-org]/geostep.git
cd geostep

# Use the Makefile for complete setup
make dev-setup
```

This installs:
- All core dependencies
- Development tools (`pytest`, `black`, `flake8`, `mypy`)
- Documentation tools (`sphinx`, `sphinx-rtd-theme`)
- Code coverage tools (`pytest-cov`)

### Method 3: Quick Installation

If you have access to the source code but want a quick, non-editable installation:

```bash
# From the GeoStep root directory
pip install .

# Or directly from GitHub (if you have access)
pip install git+https://github.com/ [your-github-org]/geostep.git
```

## Virtual Environment Setup

We strongly recommend using a virtual environment to avoid dependency conflicts:

### Using venv (Built-in)
```bash
# Create virtual environment
python -m venv geostep-env

# Activate it
# On macOS/Linux:
source geostep-env/bin/activate
# On Windows:
geostep-env\Scripts\activate

# Install GeoStep
pip install -e .

# Deactivate when done
deactivate
```

### Using conda
```bash
# Create conda environment
conda create -n geostep python=3.9
conda activate geostep

# Install GeoStep
pip install -e .

# Deactivate when done
conda deactivate
```

## Verifying Installation

### Basic Verification
```python
import geostep
print(f"GeoStep version {geostep.__version__} installed successfully!")

# Check all modules are importable
from geostep import analyzer, designer, power, visualizer
print("All modules loaded successfully!")
```

### Complete Verification
Run the built-in test to ensure everything works:

```bash
# Run a simple test analysis
python examples/run_example_analysis.py

# Or use the Makefile
make test
```

You should see Rich-formatted output with analysis results if installation is successful.

## Upgrading

### From Git Repository
```bash
cd geostep
git pull origin main
pip install -e . --upgrade
```

### Upgrading Dependencies
```bash
# Upgrade all dependencies to latest compatible versions
pip install -e . --upgrade --upgrade-strategy eager
```

## Troubleshooting Installation

### Common Issues and Solutions

#### 1. ModuleNotFoundError: No module named 'psutil'
**Problem**: Missing psutil dependency (added in recent versions)
**Solution**: 
```bash
pip install psutil
# Or reinstall GeoStep
pip install -e . --force-reinstall
```

#### 2. ImportError with statsmodels
**Problem**: Statsmodels compatibility issues
**Solution**:
```bash
pip install --upgrade statsmodels
```

#### 3. Matplotlib Backend Issues
**Problem**: Plotting fails on servers without display
**Solution**:
```python
import matplotlib
matplotlib.use('Agg')  # Use non-interactive backend
import matplotlib.pyplot as plt
```

#### 4. Permission Denied Errors
**Problem**: System-wide installation conflicts
**Solution**: Use virtual environment or user installation:
```bash
pip install --user -e .
```

#### 5. C++ Compiler Required (Windows)
**Problem**: Some dependencies need compilation
**Solution**: Install Visual Studio Build Tools or use conda:
```bash
conda install numpy scipy scikit-learn
pip install -e .
```

## Docker Installation (Optional)

For containerized deployments:

```dockerfile
FROM python:3.9-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    gcc \
    g++ \
    && rm -rf /var/lib/apt/lists/*

# Copy and install GeoStep
COPY . /app/geostep
RUN pip install -e /app/geostep

# Set working directory
WORKDIR /workspace

CMD ["python"]
```

Build and run:
```bash
docker build -t geostep .
docker run -it -v $(pwd):/workspace geostep
```

## Platform-Specific Notes

### macOS
- Ensure Xcode Command Line Tools are installed:
  ```bash
  xcode-select --install
  ```
- For M1/M2 Macs, some dependencies may need special handling:
  ```bash
  pip install --no-binary :all: --no-use-pep517 statsmodels
  ```

### Windows
- Use Anaconda/Miniconda for easier dependency management
- Run commands in Anaconda Prompt for best compatibility
- Consider using WSL2 for Linux-like environment

### Linux
- May need to install Python development headers:
  ```bash
  # Ubuntu/Debian
  sudo apt-get install python3-dev
  
  # RHEL/CentOS
  sudo yum install python3-devel
  ```

## Configuration

### Environment Variables
You can set these optional environment variables:

```bash
# Set default random seed
export GEOSTEP_RANDOM_SEED=42

# Set default output directory
export GEOSTEP_OUTPUT_DIR=/path/to/results

# Enable debug logging
export GEOSTEP_LOG_LEVEL=DEBUG
```

### Configuration File
Create a `.geostep.yml` in your project root:

```yaml
# .geostep.yml
defaults:
  random_seed: 42
  confidence_level: 0.95
  n_bootstrap: 1000
  
paths:
  data: ./data
  results: ./results
  plots: ./plots

analysis:
  use_bootstrap_ci: true
  save_plots: true
```

## Next Steps

After successful installation:

1. **[Getting Started](./getting_started.md)**: Run your first geo-experiment
2. **[Quick Test](../examples/run_example_analysis.py)**: Try the example analysis
3. **[API Documentation](./api_reference.md)**: Explore available functions
4. **[Troubleshooting](./troubleshooting.md)**: If you encounter issues

## Getting Help

If you encounter installation issues:

1. Check the [Troubleshooting Guide](./troubleshooting.md)
2. Ensure all system requirements are met
3. Try installation in a fresh virtual environment
4. Review the error messages carefully
5. Check that you have the latest version of pip:
   ```bash
   pip install --upgrade pip