Installation¶

This guide covers the installation of the Climate Diagnostics Toolkit and its dependencies.

Prerequisites¶

The Climate Diagnostics Toolkit requires:

Python 3.11 or later
NumPy, SciPy, pandas, xarray
Matplotlib and Cartopy for plotting
Dask for parallel processing and chunking
netCDF4 and bottleneck for data handling
statsmodels for statistical analysis

Environment Setup¶

We strongly recommend using conda to manage dependencies, especially for geospatial packages like Cartopy.

Using Conda (Recommended)¶

Clone the repository:

git clone https://github.com/pranay-chakraborty/climate_diagnostics.git
cd climate_diagnostics

Create the conda environment:

conda env create -f environment.yml

Activate the environment:

conda activate climate-diagnostics

Install the package in development mode:

pip install -e .

Using pip¶

If you prefer pip, ensure you have the required system dependencies for Cartopy:

On Ubuntu/Debian:

sudo apt-get update
sudo apt-get install libproj-dev proj-data proj-bin libgeos-dev

On macOS (with Homebrew):

brew install proj geos

Install the package:

pip install climate_diagnostics

Development Installation¶

For development work:

Fork and clone the repository:

git clone https://github.com/pranay-chakraborty/climate_diagnostics.git
cd climate_diagnostics

Create a development environment:

conda env create -f environment.yml
conda activate climate-diagnostics

Install in editable mode with development dependencies:

pip install -e ".[dev]"

Install pre-commit hooks:

pre-commit install

Verification¶

Test your installation:

import climate_diagnostics
import xarray as xr

# Check version
print(climate_diagnostics.__version__)

# Test basic functionality
ds = xr.tutorial.open_dataset("air_temperature")
print("✅ Installation successful!")

Optional Dependencies¶

Additional packages for enhanced functionality:

For Jupyter notebooks:

conda install jupyter ipywidgets

For faster computations:

conda install dask distributed

For advanced statistical analysis:

conda install scikit-learn statsmodels

Troubleshooting¶

Common Issues¶

Cartopy installation fails:: Use conda instead of pip for Cartopy and its dependencies.
Import errors with GEOS/PROJ:: Ensure system libraries are installed (see pip section above).
Memory issues with large datasets:: Install Dask: conda install dask
Plotting issues on headless systems:: Set the matplotlib backend: export MPLBACKEND=Agg

Getting Help¶

If you encounter issues:

Check the GitHub Issues
Search Stack Overflow
Open a new issue with: - Your OS and Python version - Full error traceback - Minimal example to reproduce the issue

System Requirements¶

Minimum: - Python 3.11+ - 4 GB RAM - 1 GB free disk space

Recommended: - Python 3.11+ - 16 GB RAM (for large datasets) - SSD storage - Multi-core CPU for parallel processing