# PrecipGen

A Python library for stochastic precipitation generation based on the Richardson & Wright (1984) WGEN algorithm.

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Overview

PrecipGen provides tools for generating synthetic daily precipitation data using the WGEN algorithm. The library supports both stationary and non-stationary climate modeling, with features for data analysis, parameter estimation, and Monte Carlo simulation.

### Key Features

- **WGEN Algorithm Implementation** - Richardson & Wright (1984) algorithm for precipitation generation
- **Data Analysis Tools** - Precipitation statistics, trend detection, and visualization
- **Multiple Data Sources** - Support for CSV files and GHCN station data
- **Parameter Estimation** - Automatic calculation of WGEN parameters from historical data
- **Monte Carlo Simulation** - Generate multiple realizations of synthetic precipitation
- **Non-stationary Modeling** - Trend detection and parameter evolution over time
- **Flexible API** - Work with your own data or use built-in data loading functions

## Quick Start

### Installation

```bash
pip install precipgen
```

For detailed installation instructions, see the [Installation Guide](installation.md).

### Basic Workflow

```python
import precipgen as pg

# Load precipitation data
precip_data = pg.load_csv_precipitation_data("precipitation.csv")

# Analyze data and estimate parameters
engine = pg.AnalyticalEngine(precip_data, wet_day_threshold=0.0254)
engine.initialize()

# View statistics and create plots
engine.print_annual_precipitation_statistics()
engine.plot_annual_precipitation(save_path='annual_precip.png')

# Generate parameters for simulation
manifest = engine.generate_parameter_manifest()

# Run simulation
simulator = pg.PrecipitationSimulator(parameters=manifest)
results = simulator.run_monte_carlo_simulation(n_realizations=100)

print(f"Generated {results['wgen'].shape[1]} realizations of synthetic data")
```

### Complete Workflow Examples

#### CSV to Simulation Workflow
```python
import precipgen as pg

# 1. Load CSV data
precip_mm = pg.load_csv_precipitation_data(
    "Logan_UT.csv", 
    station_name="Logan, UT",
    coordinates=(41.7370, -111.8338)
)

# 2. Analyze data
engine = pg.AnalyticalEngine(precip_mm, wet_day_threshold=0.0254)
engine.initialize()

# Get statistics and create plots
engine.print_annual_precipitation_statistics()
engine.plot_trend_analysis(save_path='trends.png')

# 3. Generate parameters
manifest = engine.generate_parameter_manifest()

# 4. Run simulation
simulator = pg.PrecipitationSimulator(parameters=manifest)
results = simulator.run_monte_carlo_simulation(
    start_date='2025-01-01',
    end_date='2035-12-31',
    n_realizations=50,
    methods=['wgen']
)

print(f"Simulation complete: {results['wgen'].shape}")
```

#### GHCN to Full Simulation Workflow
```python
import precipgen as pg

# 1. Load GHCN station data
workflow = pg.GHCNWorkflow(station_id="USC00425186")
historical_data = workflow.load_historical_data()

# 2. Analyze data
engine = pg.AnalyticalEngine(historical_data, wet_day_threshold=0.0254)
engine.initialize()
manifest = engine.generate_parameter_manifest()

# 3. Run simulation with multiple methods
simulator = pg.PrecipitationSimulator(
    parameters=manifest, 
    historical_data=historical_data
)
results = simulator.run_monte_carlo_simulation(
    start_date='2025-01-01',
    end_date='2030-12-31',
    methods=['wgen', 'bootstrap_doy'],
    n_realizations=25
)

print(f"Methods available: {list(results.keys())}")
```

## Visualization Examples

### Monthly WGEN Parameters
The `plot_monthly_parameters()` method creates professional column charts showing the seasonal variation in precipitation parameters:

![WGEN Parameters](images/wgen_parameters_example.png)

*Monthly WGEN parameters showing Markov chain transition probabilities (P(W|W), P(W|D)) and Gamma distribution parameters (Alpha, Beta) with seasonal patterns clearly visible.*

### Annual Precipitation Trends
The `plot_annual_precipitation()` method shows long-term precipitation patterns with automatic partial year filtering:

![Annual Precipitation](images/annual_precipitation_example.png)

*Annual precipitation totals with trend line and statistical analysis. Partial years are automatically excluded for data integrity (exclude_partial_years=True by default).*

### Seasonal Trend Analysis
The `plot_trend_analysis()` method shows parameter evolution over time with consistent seasonal color coding:

![Seasonal Trends](images/seasonal_trends_example.png)

*Seasonal parameter trends with consistent color scheme: Winter (Blue), Spring (Green), Summer (Orange), Fall (Red). Shows evolution of WGEN parameters over time using sliding window analysis.*

### Simulation Comparison
The `plot_simulation_comparison()` method creates a comprehensive 4-panel comparison between synthetic and historical data:

![Simulation Comparison](images/simulation_comparison_example.png)

*Four-panel comparison showing: (1) Annual precipitation distributions, (2) Monthly climatology (mean daily precipitation by month), (3) Daily time series sample, (4) Monthly wet day frequency. Validates synthetic data against historical patterns.*

## Core Components

### Analysis and Simulation
- **AnalyticalEngine** - Parameter estimation and data analysis
- **SimulationEngine** - WGEN-based precipitation generation
- **PrecipitationSimulator** - Monte Carlo simulation with multiple methods
- **BootstrapEngine** - Historical data resampling

### Data Management
- **GHCNWorkflow** - GHCN station data loading and processing
- **CSV Loading** - Import precipitation data from CSV files
- **DataValidator** - Data quality assessment and filtering

### Visualization and Analysis
- **Statistical Analysis** - Annual precipitation statistics and trends
- **Plotting Functions** - Create charts for parameters, trends, and comparisons
- **Parameter Visualization** - Display monthly WGEN parameters
- **Simulation Comparison** - Compare synthetic vs historical data

## Library Features

### WGEN Algorithm Implementation
- Parameter estimation from historical data
- Markov chain models for precipitation occurrence
- Gamma distribution for precipitation amounts
- Support for different wet day thresholds

### Data Analysis Tools
- Annual precipitation statistics and trends
- Monthly parameter visualization
- Trend detection with statistical significance testing
- Comparison between synthetic and historical data

### Flexible Data Sources
- CSV file import with metadata support
- GHCN station data access and processing
- Manual parameter input for simulation-only workflows

## Mathematical Foundation

Based on Richardson & Wright (1984):

- **Markov Chain Models** for precipitation occurrence
- **Gamma Distribution** for precipitation amounts  
- **Trend Detection** using sliding window analysis
- **Parameter Estimation** from historical data
- **Statistical Validation** of synthetic output

For detailed mathematical information, see the [Mathematical Foundation](mathematical_foundation.md) documentation.

## Requirements

- Python 3.8+
- NumPy
- Pandas  
- SciPy
- Matplotlib (for visualization)
- Requests (for data download)

## Documentation

- [Installation Guide](installation.md) - Get PrecipGen installed and configured
- [User Guide](user_guide.md) - Learn to use PrecipGen's features
- [API Reference](api.md) - Complete API documentation with examples
- [Mathematical Foundation](mathematical_foundation.md) - Algorithm details and theory

## License

MIT License - see [LICENSE](https://github.com/jlillywh/precipgen/blob/main/LICENSE) file for details.

## Citation

If you use PrecipGen in your research, please cite:

```
Richardson, C.W. and Wright, D.A., 1984. WGEN: A model for generating daily weather variables. US Department of Agriculture, Agricultural Research Service.
```

## Contributing

See [CONTRIBUTING.md](https://github.com/jlillywh/precipgen/blob/main/CONTRIBUTING.md) for development guidelines.

## Testing and Validation

PrecipGen includes comprehensive testing:

- **Unit Tests** - Core functionality testing with 144 passing tests
- **Algorithm Verification** - WGEN implementation validated against reference
- **Statistical Validation** - Synthetic data compared to historical patterns
- **Workflow Testing** - End-to-end workflow validation
- **Error Handling** - Robust error handling and diagnostics