Contributing

We welcome contributions to the Climate Diagnostics Toolkit! This guide will help you get started.

🤝 Ways to Contribute

🐛 Report Bugs

Found an issue? Let us know!

Report bugs on our GitHub Issues page.

💡 Suggest Features

Have an idea for improvement?

Start a discussion on our GitHub Discussions page.

📝 Improve Documentation

Help make our docs better!

Documentation improvements are always welcome.

🔧 Code Contributions

Add new features or fix bugs

Submit pull requests with new functionality.

🚀 Getting Started

1. Fork and Clone

# Fork on GitHub, then clone your fork
git clone https://github.com/pranay-chakraborty/climate_diagnostics.git
cd climate_diagnostics

2. Set Up Development Environment

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

# Install in development mode
pip install -e .

# Install development dependencies
pip install pytest black flake8 sphinx

3. Create a Branch

git checkout -b feature/your-feature-name

🧪 Development Workflow

Code Style

We use Black for code formatting:

# Format your code
black src/climate_diagnostics/

# Check formatting
black --check src/climate_diagnostics/

Testing

Run tests before submitting:

# Run all tests
pytest tests/

# Run specific test file
pytest tests/test_plots.py

# Run with coverage
pytest --cov=climate_diagnostics tests/

Documentation

Build documentation locally:

cd docs/
make html

# View in browser
open build/html/index.html

📝 Code Guidelines

Python Style

  • Follow PEP 8

  • Use Black for formatting

  • Add type hints where appropriate

  • Write descriptive docstrings

Example Function:

def calculate_trend(
    data: xr.DataArray,
    dim: str = "time",
    method: str = "linear"
) -> xr.DataArray:
    """
    Calculate linear trend along specified dimension.

    Parameters
    ----------
    data : xr.DataArray
        Input data array
    dim : str, default "time"
        Dimension along which to calculate trend
    method : str, default "linear"
        Trend calculation method

    Returns
    -------
    xr.DataArray
        Trend values with same coordinates as input

    Examples
    --------
    >>> trend = calculate_trend(temperature_data)
    """
    # Implementation here
    pass

Testing Guidelines

  • Write tests for all new functions

  • Include edge cases and error conditions

  • Use meaningful test names

  • Keep tests simple and focused

Example Test:

import pytest
import numpy as np
import xarray as xr
from climate_diagnostics.trends import calculate_trend

def test_calculate_trend_linear():
    """Test linear trend calculation with known data."""
    # Create test data with known trend
    time = pd.date_range("2000", "2010", freq="YS")
    data = xr.DataArray(
        np.arange(len(time)) + np.random.randn(len(time)) * 0.1,
        dims=["time"],
        coords={"time": time}
    )

    trend = calculate_trend(data)

    # Should be close to 1.0 per year
    assert abs(trend.values - 1.0) < 0.2

📚 Documentation Standards

Docstring Format

Use NumPy-style docstrings:

def function_name(param1, param2):
    """
    Brief description of the function.

    Longer description if needed. Explain what the function
    does, any important algorithms, or usage notes.

    Parameters
    ----------
    param1 : type
        Description of param1
    param2 : type, optional
        Description of param2 (default: value)

    Returns
    -------
    return_type
        Description of return value

    Raises
    ------
    ExceptionType
        When this exception is raised

    Examples
    --------
    >>> result = function_name(value1, value2)
    >>> print(result)
    Expected output
    """

Adding Examples

Include examples in the examples/ directory:

"""
Example: Creating Temperature Maps
=================================

This example shows how to create temperature
maps using the climate_plots accessor.
"""

import xarray as xr
import matplotlib.pyplot as plt
import climate_diagnostics

# Load data
ds = xr.open_dataset("temperature.nc")

# Create plot
fig = ds.climate_plots.plot_mean(
    variable="temperature",
    title="Global Mean Temperature"
)
plt.show()

🔄 Pull Request Process

1. Prepare Your PR

# Make sure tests pass
pytest tests/

# Format code
black src/climate_diagnostics/

# Update documentation if needed
cd docs && make html

2. Submit PR

  • Use a descriptive title

  • Reference any related issues

  • Describe what your changes do

  • Include tests for new functionality

3. PR Template

## Description
Brief description of changes

## Related Issues
Fixes #123

## Changes Made
- Added new feature X
- Fixed bug in Y
- Updated documentation for Z

## Testing
- [ ] All tests pass
- [ ] New tests added for new functionality
- [ ] Documentation updated

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated

🐛 Bug Reports

Good Bug Report Template:

## Bug Description
Clear description of what the bug is

## To Reproduce
1. Load data with `ds = xr.open_dataset(...)`
2. Call `ds.climate_plots.plot_mean(...)`
3. See error

## Expected Behavior
What you expected to happen

## Environment
- OS: [e.g. macOS 12.0]
- Python version: [e.g. 3.11.0]
- climate_diagnostics version: [e.g. 1.1.0]
- xarray version: [e.g. 2023.1.0]

## Additional Context
Any other relevant information

💬 Community Guidelines

  • Be respectful and inclusive

  • Help others learn and grow

  • Ask questions if you’re unsure

  • Share your knowledge and experience

  • Follow our Code of Conduct

📧 Getting Help

Thank you for contributing to the Climate Diagnostics Toolkit! 🙏