Log Pearson Type III Flood Frequency Analysis of Simulated Streamflow

Posted by Jason Lillywhite

Engineers frequently need to estimate design floods that exceed the range of observed data, like the 100-year or 500-year flood that may not have occurred in the historical record. While GoldSim excels at empirical analysis using historical resampling (as shown in our previous post on annual peak flow statistics), parametric flood frequency analysis using the Log Pearson Type III distribution enables extrapolation beyond observed data.

This tutorial demonstrates a useful approach for those incorporating hydrology in your water balance models. The example model used in this tutorial performs Log Pearson Type III analysis on simulated annual peak flows generated from rainfall-runoff modeling within GoldSim. Rather than being limited by short historical streamflow records, this method uses rainfall-runoff simulation to generate extended flow datasets from much longer, available climate data.

The integration shows how to implement Log Pearson Type III flood frequency analysis for engineering applications using the methodology from USGS Bulletin 17C. Included in this tutorial are the following functions:

• Simulation of streamflow using a rainfall runoff model
• Design flood estimates for standard return periods (2, 5, 10, 25, 50, 100, 200, 500 years)
• Quality assurance metrics

The integration uses GSPy (GoldSim-Python Bridge) to connect GoldSim's dynamic simulation capabilities with Python's advanced statistical analysis libraries, enabling flood frequency analysis within your existing GoldSim workflow.

Figure 1. GoldSim model results - Log Pearson Type III flood frequency analysis results with time series of daily simulated streamflow.

The Integration: Simulated Flows + Statistical Analysis

This approach combines GoldSim's modeling capabilities with Python's statistical analysis to create a dynamic flood frequency analysis model. Below is a basic description of the model setup so you can try this on your computer.

Advantages of Simulated Flow Analysis

Using simulated flows for flood frequency analysis provides benefits like:

• Extended Record Length - Use 100+ years of climate data vs. limited streamflow records
• Current Watershed Conditions - Reflects existing land use, development, and infrastructure
• Climate Variability - Captures full range of historical precipitation patterns (if expanded with a stochastic weather generator like WGEN or PrecipGen)
• Ungaged Watersheds - Enables analysis where no streamflow data exists
• Future Scenarios - Can incorporate climate change or development projections

The Modeling Process

The GoldSim model uses historical precipitation and daily temperature data (1911-2021) to simulate a rainfall-runoff process in a hypothetical watershed. The system calculates evapotranspiration using the Hargreaves-Samani method (based on temperature and latitude) and simulates watershed response using the Australian Water Balance Model (AWBM) to generate continuous daily streamflow. An Extrema element automatically captures annual peak flows throughout the 111-year simulation period, creating a robust dataset for statistical analysis.

During simulation, GoldSim annually calls the Python analysis function, but a control flag prevents execution until all annual peak data is collected. At simulation end, the flag triggers the Log Pearson Type III analysis, ensuring complete statistical processing of the entire dataset.

Figure 2. The GoldSim Model with Streamflow Simulator and Python Interface.

The External element interfaces with GSPy, a specialized DLL that provides seamless integration between GoldSim and Python statistical analysis.

---

Step 1: Configure the GoldSim-Python Interface

The integration requires four synchronized files that work together to enable the GoldSim-Python connection. All files can be downloaded using the link at the bottom of this post:

1. GSPy_LogPearson3.dll - GSPy bridge DLL (renamed from GSPy_314.dll)
2. GSPy_LogPearson3.json - Configuration file defining inputs and outputs
3. logp3_analysis.py - Python script containing Log Pearson Type III analysis implementation
4. GoldSim Log3 Model.gsm - Complete GoldSim model demonstrating the rainfall-runoff simulation and statistical analysis integration

The JSON configuration defines the interface between GoldSim and Python (refer to instructions here):

{
  "python_path": "C:\\Users\\{username}\\AppData\\Local\\Programs\\Python\\Python314",
  "script_path": "GSPy_LogPearson3.py",
  "function_name": "analyze_flood_frequency",
  "inputs": [
    {
      "name": "annual_peaks",
      "type": "vector",
      "dimensions": [111]
    },
    {
      "name": "run_script_flag", 
      "type": "scalar",
      "dimensions": [1]
    }
  ],
  "outputs": [
    {
      "name": "design_flood_matrix",
      "type": "matrix",
      "dimensions": [8, 4]
    },
    {
      "name": "quality_metrics",
      "type": "vector",
      "dimensions": [6]
    }
  ]
}

The External element in GoldSim should be linked to the DLL provided with the example or from our GSPy repository, referenced above. This DLL is 64-bit so you must run it out of process. The function name is always "GSPy" because that is just the way I wanted things. The interface tab should reflect the json file. Once this is set up, all we have left to do is write a Python script to do the heavy lifting. 

Figure 3. GoldSim External element configuration showing settings and I/O interface.

---

Step 2: Log Pearson Type III Implementation

This implementation demonstrates the Log Pearson Type III approach using method of moments parameter estimation. This fundamental methodology is suited for complete annual peak flow datasets and provides a solid foundation for flood frequency analysis, by executing these functions:

Data Validation and Quality Control

• Removal of zero and negative flow values
• Basic outlier detection using interquartile range (IQR) method
• Minimum data requirements assessment (10+ years recommended)
• Statistical validation of distribution parameters

Log Pearson Type III Distribution Fitting

• Base-10 logarithmic transformation of flow data
• Method of moments parameter estimation
• Calculation of mean, standard deviation, and skewness in log-space
• Parameter validation and reasonableness checks

Design Flood Calculation with Uncertainty

• Inverse cumulative distribution function (quantile) calculation
• Standard return periods: 2, 5, 10, 25, 50, 100, 200, 500 years
• Bootstrap confidence interval estimation
• Basic quality assurance metrics

The Log Pearson Type III approach enables extrapolation to estimate extreme events beyond the observed record, which is useful for infrastructure design where you need to estimate floods that may not have occurred during the simulation period. USGS Bulletin 17C specifies this distribution as the federal standard for flood frequency analysis.

The Python implementation includes logging for educational purposes and troubleshooting. GSPy provides configurable logging levels in the JSON file, allowing you to control output verbosity from minimal error-only logging to detailed step-by-step analysis information (refer to documentation here).

---

Step 3: Understanding the Output

The Python script returns design flood estimates along with basic analysis information. The output is sent to GoldSim via GSPy just before the simulation completes (on the last time step). This output structure allows users to review what the calculations produced:

GSPy-LogPearson3 Output Structure:

Design Flood Matrix (8×4):
  Column 1: Return Periods [2, 5, 10, 25, 50, 100, 200, 500]
  Column 2: Design Floods [point estimates in m³/s or cfs]
  Column 3: Lower 95% confidence bounds
  Column 4: Upper 95% confidence bounds

Analysis Information Vector (6 elements):
  Element 1: Kolmogorov-Smirnov p-value
  Element 2: Probability plot correlation (R²)
  Element 3: Data adequacy score (0-1, based on record length)
  Element 4: Skewness quality indicator (0-1)
  Element 5: Basic methodology compliance (0-1)
  Element 6: Overall confidence score (0-1)
        

Educational Purpose: The analysis information is provided for learning purposes. Users should consult with qualified professionals for regulatory applications and rely on established software like USGS PeakFQ for official flood frequency analysis.

Figure 4. Model Outputs in this Example

Real-World Application: 100-Year Simulation Results

This model was tested using a 111-year simulation of a hypothetical watershed in an arid region. Precipitation and min/max daily temperature values were obtained from here, measured at Australia Pains, AU. I just picked this location because I happened to have good data from that location.

Running the weather data through an evapotranspiration and rainfall-runoff model, I captured the annual peak flow values in an array, which gets sent to the Python script as described above.

Figure 5. Sample of the annual peak flow values for this example site.

Before GoldSim finishes completely, it executes the Python script and brings the data into the GoldSim model so we can incorporate it into more calculations downstream in the model and we can display them in tables and charts in a dashboard.

Figure 6. GoldSim Final Value Result Chart Log Pearson III Flood Frequency Analysis Result.

You can play with the model to check out all the results and see if this might be useful for you.

Download and Implementation

The download includes:

• Example GoldSim model with configured External element
• Python script
• GSPy configuration JSON file
• GSPy DLL
• Minimal instructions

You can download the complete working example here: GoldSim-Python LPIII Integration.zip

This integration demonstrates a practical approach to flood frequency analysis within GoldSim, delivering the results engineers need: design flood estimates and basic quality indicators. While this tutorial implements the foundational Log Pearson Type III methodology rather than the full Bulletin 17C Expected Moments Algorithm, it provides a solid framework for routine engineering applications and can serve as a foundation for more advanced implementations.

Happy modeling!