Metadata-Version: 2.4
Name: precipgen
Version: 0.3.1
Summary: A Python library for stochastic precipitation generation using WGEN algorithms
Home-page: https://github.com/jlillywh/precipgen
Author: PrecipGen Development Team
Author-email: PrecipGen Development Team <jlillywhite@goldsim.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/jlillywh/precipgen
Project-URL: Repository, https://github.com/jlillywh/precipgen
Project-URL: Documentation, https://jlillywh.github.io/precipgen/
Project-URL: Bug Tracker, https://github.com/jlillywh/precipgen/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: Hydrology
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: pyyaml>=5.4.0
Requires-Dist: requests>=2.25.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0.0; extra == "dev"
Requires-Dist: hypothesis>=6.0.0; extra == "dev"
Requires-Dist: black>=21.0.0; extra == "dev"
Requires-Dist: flake8>=3.9.0; extra == "dev"
Requires-Dist: mypy>=0.910; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "docs"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 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)
[![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.

### 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
```

### 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 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](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](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](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](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.

## 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
