Installation

Requirements

System Requirements:

  • Python 3.8 or higher
  • 8GB RAM minimum (16GB recommended for regional datasets)
  • 64GB+ RAM recommended for global-scale processing
  • 10GB free disk space

Core Python Dependencies:

  • numpy - Numerical computations
  • scipy - Statistical distributions
  • xarray - Multi-dimensional arrays
  • netCDF4 - NetCDF file I/O
  • numba - Performance acceleration
  • matplotlib - Visualization

Dependencies for Global-Scale Processing:

  • dask[complete] - Parallel/distributed computing
  • zarr - Efficient chunked array storage
  • psutil - Memory detection and monitoring

Installation Steps

1. Clone the Repository

git clone https://github.com/bennyistanto/precip-index.git
cd precip-index

2. Install Dependencies

Option B: Using conda

conda create -n precip-index python=3.10
conda activate precip-index
conda install -c conda-forge numpy scipy xarray netCDF4 numba matplotlib dask zarr psutil

3. Verify Installation

Run the test suite to verify everything works:

python tests/run_all_tests.py

Expected output:

======================================================================
PRECIP-INDEX TEST SUITE
======================================================================
Running all integration tests...
Dataset: TerraClimate Bali (1958-2024)

Checking input data files...
  [OK] input/terraclimate_bali_ppt_1958_2024.nc (0.8 MB)
  [OK] input/terraclimate_bali_tmean_1958_2024.nc (1.7 MB)
  [OK] input/terraclimate_bali_pet_1958_2024.nc (0.8 MB)

...

[OK] All tests passed!

Directory Structure

After installation, you should have:

precip-index/
├── src/                    # Source code
│   ├── indices.py         # SPI/SPEI calculations
│   ├── compute.py         # Core computation algorithms
│   ├── distributions.py   # Multi-distribution fitting (Gamma, Pearson III, etc.)
│   ├── chunked.py         # Memory-efficient global processing
│   ├── config.py          # Configuration and constants
│   ├── runtheory.py       # Event analysis
│   ├── visualization.py   # Plotting functions
│   └── utils.py           # Utilities and memory tools
├── input/                 # Example data
│   ├── terraclimate_bali_ppt_1958_2024.nc
│   ├── terraclimate_bali_tmean_1958_2024.nc
│   └── terraclimate_bali_pet_1958_2024.nc
├── notebook/              # Jupyter tutorials
│   ├── 01_calculate_spi.ipynb
│   ├── 02_calculate_spei.ipynb
│   ├── 03_event_characteristics.ipynb
│   ├── 04_visualization_gallery.ipynb
│   └── 05_global_scale_processing.ipynb
├── tests/                 # Test suite
│   └── run_all_tests.py
├── docs/                  # Documentation
├── requirements.txt       # Dependencies
└── README.md

Setup Python Path

Before using the package, add the src directory to your Python path:

import sys
sys.path.insert(0, 'src')  # Relative path from project root

Or use an absolute path:

import sys
sys.path.insert(0, '/path/to/precip-index/src')
TipIDE Setup

For Jupyter notebooks or IDEs, you can set the Python path once at the beginning of your session, and it will persist throughout your work.

Verify Your Setup

Test that imports work correctly:

import sys
sys.path.insert(0, 'src')

# Test imports
from indices import spi, spei, spi_multi_scale
from indices import spi_global, spei_global  # Global-scale processing
from runtheory import identify_events, calculate_timeseries
from visualization import plot_index, plot_events
from chunked import ChunkedProcessor, estimate_memory

print("✓ All imports successful!")

Optional: Jupyter Notebook Support

If you want to run the tutorial notebooks:

pip install jupyter jupyterlab

Then launch Jupyter:

jupyter lab

Navigate to the notebook/ directory and open any tutorial.

Troubleshooting

Issue: ModuleNotFoundError

Problem: ModuleNotFoundError: No module named 'indices'

Solution: Make sure you’ve added the src directory to your Python path:

import sys
sys.path.insert(0, 'src')

Issue: Import Errors for Dependencies

Problem: ModuleNotFoundError: No module named 'xarray'

Solution: Install the missing dependency:

pip install xarray

Or install all dependencies at once:

pip install -r requirements.txt

Issue: Numba Installation Fails

Problem: Numba installation fails on some systems

Solution: Try installing via conda instead:

conda install -c conda-forge numba

Or use the package without Numba acceleration (slower but still functional).

Next Steps

✓ Installation complete!

Now you’re ready to:

  1. Follow the Quick Start - Calculate your first SPI/SPEI
  2. Try the Tutorials - Learn through interactive examples
  3. Read the User Guide - Understand the methodology

Getting Help

If you encounter issues:

  1. Check the Quick Start Guide for common solutions
  2. Review the test results for validation examples
  3. Open an issue on GitHub

See Also

Back to top