precipgen 0.3.3
A Python library for stochastic precipitation generation using WGEN algorithms
Requires Python: >=3.8

# PrecipGen

A Python library for stochastic precipitation generation based on the Richardson & Wright (1984) WGEN algorithm.

[![PyPI version](https://badge.fury.io/py/precipgen.svg)](https://badge.fury.io/py/precipgen)
[![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)
[![Documentation](https://img.shields.io/badge/docs-live-brightgreen.svg)](https://jlillywh.github.io/precipgen/)

## 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.

**Latest Update (v0.3.3):** Critical bug fixes ensure reliable imports and GHCN data access without workarounds.

### 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
```

PrecipGen is now available on [PyPI](https://pypi.org/project/precipgen/) and can be installed with a single command.

### 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")
```

**Sample Output:** When you run `engine.plot_annual_precipitation()`, you'll get a chart like this:

![Annual Precipitation Example](docs/images/quickstart_annual_precip.png)

*Annual precipitation totals from Logan, UT (1900-2021) showing long-term trends and statistical analysis. This chart is generated automatically when you run the quickstart code above.*

### Complete Workflow Examples

#### CSV Data 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 Data 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())}")
```

#### Synthetic Data Analysis
```python
# Analyze synthetic data with same tools as historical data
synthetic_data = results['wgen'].iloc[:, 0]  # First realization

synthetic_engine = pg.AnalyticalEngine(synthetic_data, wet_day_threshold=0.0254)
synthetic_engine.initialize()
synthetic_engine.print_annual_precipitation_statistics()
synthetic_engine.plot_annual_precipitation(save_path='synthetic_annual.png')
```

#### Enhanced Visualization Features
```python
# Automatic parameter visualization
engine.plot_monthly_parameters(save_path='wgen_parameters.png')

# Annual precipitation trends with data integrity filtering
engine.plot_annual_precipitation(
    exclude_partial_years=True,  # Default: filters incomplete years
    save_path='annual_trends.png'
)

# Seasonal trend analysis with consistent color coding
engine.plot_trend_analysis(save_path='seasonal_trends.png')
# Winter=Blue, Spring=Green, Summer=Orange, Fall=Red

# Comprehensive simulation comparison (4-panel figure)
simulator.plot_simulation_comparison(
    historical_data=historical_precip,
    save_path='simulation_comparison.png'
)
```

## Visualization Examples

### Monthly WGEN Parameters
The `plot_monthly_parameters()` method creates professional column charts showing the seasonal variation in precipitation parameters:

![WGEN Parameters](https://raw.githubusercontent.com/jlillywh/precipgen/main/docs/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](https://raw.githubusercontent.com/jlillywh/precipgen/main/docs/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](https://raw.githubusercontent.com/jlillywh/precipgen/main/docs/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](https://raw.githubusercontent.com/jlillywh/precipgen/main/docs/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.*

### Advanced Integration Features

#### Workflow Integration API
```python
from precipgen.api.workflow_integration import WorkflowIntegrator

# Automated workflow with caching and optimization
integrator = WorkflowIntegrator(enable_caching=True)

results = integrator.create_integrated_workflow(
    data_source="precipitation.csv",
    analysis_config={'wet_day_threshold': 0.0254},
    simulation_config={'n_realizations': 100, 'methods': ['wgen']}
)

if results['success']:
    print(f"✓ Complete workflow: {results['simulation_results']['wgen'].shape}")
```

#### Standardized API for External Integration
```python
from precipgen.api import StandardizedAPI

# Standardized interface using only Python built-in types
api = StandardizedAPI()

# Analyze data with dictionary interface
result = api.analyze_data(
    data=precipitation_values,
    analysis_config={'wet_day_threshold': 0.0254}
)

if result['success']:
    monthly_params = result['monthly_parameters']
    print(f"January P(W|W): {monthly_params[1]['p_ww']:.3f}")
```

## 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

## Requirements

- Python 3.8+
- NumPy
- Pandas  
- SciPy
- Matplotlib (for visualization)
- Requests (for data download)

## Documentation

📚 **[Complete Documentation](https://jlillywh.github.io/precipgen/)** - Installation, API Reference, User Guide, and Mathematical Foundation

### Building Documentation Locally

To build and serve the documentation locally:

```bash
# Install documentation dependencies
pip install -e ".[docs]"

# Serve documentation with live reload
mkdocs serve
```

Visit `http://127.0.0.1:8000` to view the documentation. The site automatically updates when you make changes to documentation files or docstrings.

For detailed documentation development guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md#documentation-development-setup).

## License

MIT License - see [LICENSE](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](CONTRIBUTING.md) for development guidelines.

## Release Notes

### v0.3.3 (Latest)
- **Critical Bug Fixes**
  - Fixed missing typing imports that caused NameError exceptions
  - Updated GHCN URLs to current NOAA domain (www.ncei.noaa.gov)
  - Improved import reliability - no longer requires workarounds
  - Fixed convenience API type annotations and imports
- **Stability Improvements**
  - All core functionality now works without monkey-patching
  - Enhanced error handling for missing dependencies
  - Improved test coverage and validation

### v0.3.2
- Fixed image links to use GitHub raw URLs for PyPI display
- Images now display properly on PyPI project page

### v0.3.1
- Initial PyPI release
- WGEN algorithm implementation with trend analysis
- Support for CSV and GHCN data sources
- Monte Carlo simulation capabilities
- Comprehensive testing suite (144+ tests)

For detailed changes, see [CHANGELOG.md](CHANGELOG.md).

## 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