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 2: Developer Installation

For contributors and developers who need testing and documentation tools:

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

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

# 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

# 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

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:

# 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

cd geostep
git pull origin main
pip install -e . --upgrade

Upgrading Dependencies

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

pip install psutil
# Or reinstall GeoStep
pip install -e . --force-reinstall

2. ImportError with statsmodels

Problem: Statsmodels compatibility issues Solution:

pip install --upgrade statsmodels

3. Matplotlib Backend Issues

Problem: Plotting fails on servers without display Solution:

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:

pip install --user -e .

5. C++ Compiler Required (Windows)

Problem: Some dependencies need compilation Solution: Install Visual Studio Build Tools or use conda:

conda install numpy scipy scikit-learn
pip install -e .

Docker Installation (Optional)

For containerized deployments:

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:

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

Platform-Specific Notes

macOS

  • Ensure Xcode Command Line Tools are installed:

    xcode-select --install

  • For M1/M2 Macs, some dependencies may need special handling:

    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:

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

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

# .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: Run your first geo-experiment

  2. Quick Test: Try the example analysis

  3. API Documentation: Explore available functions

  4. Troubleshooting: If you encounter issues

Getting Help

If you encounter installation issues:

  1. Check the Troubleshooting Guide

  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:

    pip install --upgrade pip