Skip to content

Installation

This guide will help you install DisruptSC and set up the required environment.

System Requirements

  • Python: 3.10 or 3.11 (required)
  • Operating System: Windows, macOS, or Linux
  • Memory: Minimum 8GB RAM (16GB+ recommended for large models)
  • Storage: 5GB+ free space for data and outputs

Step 1: Clone the Repository

Clone the public code repository:

git clone https://github.com/ccolon/disrupt-sc.git
cd disrupt-sc

The public repository includes bundled demo data for Testkistan. For full country and regional datasets, clone the private data repository next to the code repository:

cd ..
git clone <private-data-repo-url> disrupt-sc-data
cd disrupt-sc

With this sibling layout, DisruptSC automatically uses ../disrupt-sc-data. If the data repository is elsewhere, set DISRUPT_SC_DATA_PATH to that folder.

Step 2: Environment Setup

We recommend using Conda for environment management to ensure reproducible installations.

# Create environment from file
conda env create -f dsc-environment.yml

# Activate environment
conda activate dsc

# Install package in development mode
pip install -e .

Option B: Pip Installation

If you prefer using pip or don't have Conda installed:

# Create virtual environment
python -m venv dsc-env

# Activate environment
# On Windows:
dsc-env\Scripts\activate
# On macOS/Linux:
source dsc-env/bin/activate

# Install dependencies
pip install -e .

Step 3: Verify Installation

Test that DisruptSC is correctly installed:

# Check version
python -c "import disruptsc; print(disruptsc.__version__)"

# Test CLI
disruptsc --version

# Run input validation (requires data setup)
validate-inputs --help

Dependencies

DisruptSC relies on several key packages:

Core Dependencies

  • pandas - Data manipulation and analysis
  • numpy - Numerical computing
  • geopandas - Geospatial data processing
  • networkx - Graph/network analysis
  • scipy - Scientific computing
  • shapely - Geometric operations

Optional Dependencies

  • matplotlib - Basic plotting
  • plotly - Interactive visualizations
  • jupyter - Notebook environment for analysis

Troubleshooting

Common Installation Issues

Full datasets are not found

DisruptSC uses DISRUPT_SC_DATA_PATH when set. Otherwise, bundled ./examples/data/Testkistan is used for Testkistan, and other scopes are loaded from ../disrupt-sc-data.

# Check the resolved data root
python -c "from disruptsc.paths import get_data_root; print(get_data_root())"

# If using the sibling layout, verify the private repo exists
ls ../disrupt-sc-data
Conda environment creation hangs

The environment creation may get stuck in the "solving environment" step. Try:

# Clear conda cache
conda clean --all

# Use libmamba solver (faster)
conda install -n base conda-libmamba-solver
conda config --set solver libmamba

# Retry environment creation
conda env create -f dsc-environment.yml
Geospatial package installation fails

GeoPandas and related packages can be tricky to install. Solutions:

# Install from conda-forge (recommended)
conda install -c conda-forge geopandas

# Or use mamba (faster conda alternative)
mamba install geopandas
Import errors after installation

If you get import errors when running DisruptSC:

# Make sure environment is activated
conda activate dsc

# Reinstall in development mode
pip install -e .

# Check Python path
python -c "import sys; print(sys.path)"

Environment Issues

If you encounter environment conflicts:

# Remove existing environment
conda env remove -n dsc

# Recreate clean environment
conda env create -f dsc-environment.yml

# Alternative: create minimal environment and install manually
conda create -n dsc python=3.11
conda activate dsc
pip install -e .

Development Installation

For developers contributing to DisruptSC:

# Clone the code repository
git clone https://github.com/ccolon/disrupt-sc.git
cd disrupt-sc

# Create development environment
conda env create -f dsc-environment.yml
conda activate dsc

# Install in development mode with test dependencies
pip install -e ".[dev,test]"

# Install pre-commit hooks
pre-commit install

What's Next?

After successful installation:

  1. Set up your data sources - Configure input data
  2. Run the quick start example - Test your installation
  3. Validate your inputs - Ensure data quality

Getting Help

If you're still having trouble:

  • Review the common issues above
  • Search existing issues
  • Open a new issue with your error message and system details