precipgen 0.3.1

A Python library for stochastic precipitation generation using WGEN algorithms

PrecipGen

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

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

pip install precipgen

Basic Workflow

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

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

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

# 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

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

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

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

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

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 - Installation, API Reference, User Guide, and Mathematical Foundation

Building Documentation Locally

To build and serve the documentation locally:

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

License

MIT License - see 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 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