SWMM5 Delphi GUI Ustats.pas Summary

 Below is a high-level summary of the Ustats.pas unit, which analyzes continuous SWMM simulation results to extract and characterize events (e.g., rainfall, flow, load events) and compute their statistical properties. This unit is invoked primarily via its GetStats(...) procedure, which returns both a list of individual events and overall summary statistics.

---

1. Purpose & Overview

• Identifies “events” that occur over a SWMM simulation based on user-defined criteria (e.g., minimum value of a chosen variable, minimum volume, and minimum inter-event separation).
• Computes additional properties for each event (like peak value, total volume, or mean concentration).
• Ranks the events (e.g., largest to smallest) and calculates summary statistics (mean, standard deviation, skew, min, max, frequency).
• Allows results to be displayed or processed further (e.g., frequency analysis, plotting a return-period graph).

The main entry point is the function:

GetStats(var StatsSel: TStatsSelection; EventList: TList; var Results: TStatsResults);

---

2. Key Data Structures

1. TStatsSelection

   • Specifies the type of object (subcatch, node, link) and variable to be analyzed.
   • Includes thresholds like MinEventValue, MinEventVolume, MinEventDelta (minimum hours between consecutive events).
   • Defines the aggregation period (TTimePeriod) and the statistic to compute (peak, mean, total, duration, etc.).

2. TStatsEvent

   • Records information about one event found in the simulation:
     • StartDate: event’s start
     • Value: user-chosen statistic for that event (e.g., peak flow, total volume, average concentration, etc.)
     • Duration: event length
     • Rank: rank order among all events found

3. TStatsResults

   • Contains aggregate statistics over all events: mean, max, min, standard deviation, skew, total number of events, etc.

4. EventList: TList

   • A standard Delphi TList that will hold pointers (PStatsEvent) to all identified events.
   • After GetStats() completes, it is sorted by event value so that event i’s rank can be determined.

---

3. Principal Functions & Procedures

GetStats(...)

• Highest-level routine called by external code.
• Steps:
  1. Saves parameters from StatsSel to a local variable.
  2. Calls FindDuration to figure out total analysis period in months/years.
  3. Calls FindEvents to parse the simulation results and form discrete events.
  4. Calls RankEvents to sort these events by descending value and assign ranks.
  5. Calls FindStats to compute summary statistics (mean, stdev, skew, etc.).

Event-Finding Routines

1. FindEvents(EventList: TList)

   • Loops through each simulation reporting period.
   • Retrieves the current variable value (and possibly flow if needed) from the binary .out file (via Uoutput.GetValue(...)).
   • If above threshold, accumulates event stats.
   • If we cross the threshold for dryness (min. inter-event separation), finalizes one event and starts a new one.
   • Ultimately populates EventList with PStatsEvent records.

2. IsNewEventPeriod(...)

   • Checks if we’ve crossed a daily/monthly/annual boundary (or for tpVariable, uses dryness to determine event separation).

3. AddNewEvent(EventList: TList, NewDate: TDateTime)

   • If a new event truly ended, calculates the event’s value (peak, total, etc.), then appends a new PStatsEvent to EventList.

Event Ranking & Statistics

1. RankEvents(EventList: TList)

   • Sorts EventList by event value in descending order.
   • Assigns rank 1 to the largest event, rank 2 to the next, etc. (ties get the same rank).

2. FindStats(EventList: TList, var Results: TStatsResults)

   • Using the final, sorted list of events, compute:
     • Min & Max event value
     • Mean and Standard Deviation (1st and 2nd moments)
     • Skewness (3rd moment)

---

4. Interactions with Other Units

• Uoutput: Accesses SWMM simulation .out file data via GetValue() for each node/link/subcatch at each time step.
• Uproject / Uglobals: Retrieve global SWMM run data (time steps, start date/time, etc.).

---

5. Constraints & Usage

• The user must specify correct StatsSel info:
  • A valid object ID that actually exists in the SWMM model
  • A valid variable index that refers to a flow, concentration, etc.
• For flow-based or concentration-based events, this code also references a FlowVarIndex if computing load.
• The procedure assumes the simulation’s binary results (.out) are available (i.e., the run has completed).
• If no events pass thresholds, the event list can be empty, resulting in zero or trivial stats.

---

6. Example Flow

Suppose you want peak flows that exceed 2 cfs, separated by at least 6 hours of dryness:

1. Set MinEventDelta = 6, MinEventValue = 2, StatsType = stPeak, TimePeriod = tpVariable in StatsSel.
2. Call GetStats(StatsSel, EventList, Results).
3. The code scans time steps, marks new events whenever dryness > 6 hours, logs each event’s peak flow in EventList.
4. RankEvents sorts them from largest to smallest, FindStats computes the descriptive stats.

---

7. Conclusion

Ustats.pas provides a flexible mechanism for post-processing a simulation’s time series data into events and deriving statistical measures. By letting the user define event thresholds and variables, it can handle peak flows, volumes, pollutant loads, or concentrations. This is extremely helpful for hydrologic frequency analysis and for summarizing how often certain extremes occur in the simulated period.