diff --git a/CITATION.cff b/CITATION.cff index a8e4bb0..e73ce37 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -36,6 +36,10 @@ authors: given-names: "Brian" affiliation: "Fariborz Maseeh Department of Mathematics and Statistics, Portland State University, Portland, Oregon, USA" orcid: "https://orcid.org/0000-0002-2164-0301" + - family-names: "Niblett" + given-names: "Sadie" + affiliation: "U.S. Army Corps of Engineers, Risk Management Center, Lakewood, Colorado, USA" + orcid: ""https://orcid.org/0009-0008-8588-4816"" contact: - family-names: "Smith" given-names: "C. Haden" diff --git a/examples/1-time-series-data/1-usgs-download/usgs-download-example.bestfit b/examples/1-time-series-data/1-usgs-download/usgs-download-example.bestfit index b22583e..627cf77 100644 Binary files a/examples/1-time-series-data/1-usgs-download/usgs-download-example.bestfit and b/examples/1-time-series-data/1-usgs-download/usgs-download-example.bestfit differ diff --git a/examples/1-time-series-data/1-usgs-download/usgs-download-example.md b/examples/1-time-series-data/1-usgs-download/usgs-download-example.md index d264981..fc9f525 100644 --- a/examples/1-time-series-data/1-usgs-download/usgs-download-example.md +++ b/examples/1-time-series-data/1-usgs-download/usgs-download-example.md @@ -52,19 +52,22 @@ This project contains 8 time series elements from 4 USGS gaging stations: 4. The Project Explorer will show 8 elements under **Time Series Data** ![RMC-BestFit Project Explorer showing all 8 USGS time series elements](../images/usgs-project-explorer.png) + *Figure 1: Project Explorer with all USGS time series elements* ### Exploring Daily Discharge (Moose River) 1. Click **USGS - 01134500 - Daily Discharge** in the Project Explorer -2. The **Time Series** tab displays the full daily hydrograph -3. Click the **Seasonality** tab to see the annual cycle of streamflow -- note the spring snowmelt peak typical of New England rivers -4. Click the **ACF** and **PACF** tabs to view the autocorrelation structure of daily flows +2. The **Time Series** tab on the left displays the full daily hydrograph +3. Click the **Seasonality** tab on the left to see the annual cycle of streamflow -- note the spring snowmelt peak typical of New England rivers +4. Click the **ACF** and **PACF** tabs on the left to view the autocorrelation structure of daily flows ![Time series plot showing daily discharge for Moose River at Victory, VT](../images/usgs-daily-discharge-ts-plot.png) + *Figure 2: Daily discharge hydrograph for Moose River at Victory, VT (USGS 01134500)* ![Seasonality plot for Moose River daily discharge showing spring snowmelt peak](../images/usgs-daily-discharge-seasonality.png) + *Figure 3: Seasonality plot for Moose River* ### Exploring Instantaneous Data (Potomac River) @@ -75,6 +78,7 @@ This project contains 8 time series elements from 4 USGS gaging stations: 4. Zoom in on individual flood events to see the high-resolution hydrograph shape ![Time series plot showing instantaneous discharge for Potomac River](../images/usgs-instantaneous-discharge-ts-plot.png) + *Figure 4: Instantaneous discharge for Potomac River near Washington, DC (USGS 01646500)* ### Exploring Peak Data (Back Creek) @@ -85,6 +89,7 @@ This project contains 8 time series elements from 4 USGS gaging stations: 4. Click **USGS - 01614000 - Peak Stage** to see the corresponding annual peak gage heights ![Time series plot showing annual peak discharge for Back Creek near Jones Springs, WV](../images/usgs-peak-discharge-ts-plot.png) + *Figure 5: Annual peak discharge for Back Creek near Jones Springs, WV (USGS 01614000)* ### Exploring Measured Data (Susquehanna River) @@ -94,6 +99,7 @@ This project contains 8 time series elements from 4 USGS gaging stations: 3. Measured discharge and stage pairs are commonly used for rating curve development ![Time series plot showing individual field measurements for Susquehanna River](../images/usgs-measured-discharge-ts-plot.png) + *Figure 6: Field-measured discharge for Susquehanna River at Harrisburg, PA (USGS 01570500)* ### Viewing the Properties Panel @@ -106,14 +112,15 @@ This project contains 8 time series elements from 4 USGS gaging stations: - **Download** button to refresh the data from USGS NWIS ![Properties panel showing USGS site number, data type dropdown, and Download button](../images/usgs-properties-panel.png) + *Figure 7: Properties panel for a USGS time series element* ### Downloading Your Own USGS Data To create a new USGS time series element from scratch: -1. Right-click **Time Series Data** in the Project Explorer and select **Create New** -2. In the Properties panel, set **Entry Method** to **USGS** +1. Right-click **Time Series Data** in the Project Explorer and select **New Time Series** +2. After naming the time series, in the Properties panel, set **Entry Method** to **USGS** 3. Enter a valid **USGS Site Number** (8-15 digits). You can look up site numbers at https://waterdata.usgs.gov 4. Select the desired **Data Type** from the dropdown 5. Click **Download** diff --git a/examples/1-time-series-data/2-ghcn-download/ghcn-download-example.bestfit b/examples/1-time-series-data/2-ghcn-download/ghcn-download-example.bestfit index 5af15ae..ca36ff1 100644 Binary files a/examples/1-time-series-data/2-ghcn-download/ghcn-download-example.bestfit and b/examples/1-time-series-data/2-ghcn-download/ghcn-download-example.bestfit differ diff --git a/examples/1-time-series-data/2-ghcn-download/ghcn-download-example.md b/examples/1-time-series-data/2-ghcn-download/ghcn-download-example.md index 28e135d..4eb5f76 100644 --- a/examples/1-time-series-data/2-ghcn-download/ghcn-download-example.md +++ b/examples/1-time-series-data/2-ghcn-download/ghcn-download-example.md @@ -54,19 +54,22 @@ This project contains 2 time series elements from cooperative observer stations 4. The Project Explorer will show 2 elements under **Time Series Data** ![RMC-BestFit Project Explorer showing the 2 GHCN time series elements](../images/ghcn-project-explorer.png) + *Figure 1: Project Explorer with GHCN time series elements* ### Exploring Daily Precipitation (Big Bear Lake) 1. Click **GHCN - USC00040741 - Daily Precipitation** in the Project Explorer -2. The **Time Series** tab displays the daily precipitation record +2. The **Time Series** tab on the left displays the daily precipitation record 3. Notice the episodic nature of precipitation -- many zero values with occasional storms -4. Click the **Seasonality** tab to see the wet season (winter) and dry season (summer) pattern typical of California's Mediterranean climate +4. Click the **Seasonality** tab on the left to see the wet season (winter) and dry season (summer) pattern typical of California's Mediterranean climate ![Time series plot showing daily precipitation for Big Bear Lake, CA](../images/ghcn-precipitation-ts-plot.png) + *Figure 2: Daily precipitation for Big Bear Lake, CA (GHCN USC00040741)* -![Seasonality plot for Big Bear Lake precipitation showing winter wet season](../images/ghcn-precipitation-seasonality.png) +![Seasonality plot for Big Bear Lake precipitation showing winter wet season](../images/ghcn-precipitation-seasonality-plot.png) + *Figure 3: Seasonality plot -- California's Mediterranean climate with winter-dominant precipitation* ### Exploring Daily Snowfall (Paradise) @@ -77,6 +80,7 @@ This project contains 2 time series elements from cooperative observer stations 4. The **Seasonality** tab clearly shows the November-March snow season ![Time series plot showing daily snowfall for Paradise, CA](../images/ghcn-snow-ts-plot.png) + *Figure 4: Daily snowfall for Paradise, CA (GHCN USC00046685)* ### Viewing the Properties Panel @@ -90,14 +94,15 @@ This project contains 2 time series elements from cooperative observer stations - **Download** button to refresh the data ![Properties panel showing GHCN site number, data type, depth unit, and Download button](../images/ghcn-properties-panel.png) + *Figure 5: Properties panel for a GHCN time series element* ### Downloading Your Own GHCN Data To create a new GHCN time series element: -1. Right-click **Time Series Data** in the Project Explorer and select **Create New** -2. In the Properties panel, set **Entry Method** to **GHCN** +1. Right-click **Time Series Data** in the Project Explorer and select **New Time Series** +2. After naming the time series, in the Properties panel, set **Entry Method** to **GHCN** 3. Enter a valid **GHCN Station ID** (11 characters, e.g., `USC00040741`) 4. Select the **Data Type** (Daily Precipitation or Daily Snow) 5. Select the **Depth Unit** (Inches, Millimeters, or Centimeters) diff --git a/examples/1-time-series-data/3-chmn-download/chmn-download-example.bestfit b/examples/1-time-series-data/3-chmn-download/chmn-download-example.bestfit index b83a1fd..5158fe4 100644 Binary files a/examples/1-time-series-data/3-chmn-download/chmn-download-example.bestfit and b/examples/1-time-series-data/3-chmn-download/chmn-download-example.bestfit differ diff --git a/examples/1-time-series-data/3-chmn-download/chmn-download-example.md b/examples/1-time-series-data/3-chmn-download/chmn-download-example.md index 4de1f22..09fe1a1 100644 --- a/examples/1-time-series-data/3-chmn-download/chmn-download-example.md +++ b/examples/1-time-series-data/3-chmn-download/chmn-download-example.md @@ -61,20 +61,23 @@ This project contains 6 time series elements, all from the same station: 4. The Project Explorer will show 6 elements under **Time Series Data** ![RMC-BestFit Project Explorer showing all 6 CHMN time series elements for station 08MG005](../images/chmn-project-explorer.png) + *Figure 1: Project Explorer with all CHMN time series elements* ### Exploring Daily Discharge 1. Click **CHMN - 08MG005 - Daily Discharge** in the Project Explorer -2. The **Time Series** tab displays the daily streamflow record beginning in 1914 +2. The **Time Series** tab on the left displays the daily streamflow record beginning in 1914 3. Notice the strong seasonal pattern: low winter baseflow and high summer flows from snowmelt and glacial melt -4. Click the **Seasonality** tab to see the annual flow cycle peaking in June-July -5. The **ACF** tab shows strong serial correlation typical of daily streamflow +4. Click the **Seasonality** on the left tab to see the annual flow cycle peaking in June-July +5. The **ACF** tab on the left shows strong serial correlation typical of daily streamflow ![Time series plot showing daily discharge for Lillooet River](../images/chmn-daily-discharge-ts-plot.png) + *Figure 2: Daily discharge for Lillooet River near Pemberton, BC (CHMN 08MG005)* ![Seasonality plot for Lillooet River showing summer snowmelt/glacial melt peak](../images/chmn-daily-discharge-seasonality.png) + *Figure 3: Seasonality plot -- glacial-fed river with June-July peak typical of Coast Mountain catchments* ### Exploring Peak Discharge @@ -84,6 +87,7 @@ This project contains 6 time series elements, all from the same station: 3. Peak data is the most commonly used input for flood frequency analysis and can be used directly in a Univariate Analysis element without extracting annual maxima from daily data ![Time series plot showing annual peak discharge values for Lillooet River](../images/chmn-peak-discharge-ts-plot.png) + *Figure 4: Annual peak discharge for Lillooet River (CHMN 08MG005)* ### Exploring Instantaneous Data @@ -94,6 +98,7 @@ This project contains 6 time series elements, all from the same station: 4. Note: instantaneous data from WSC is typically limited to the recent real-time period ![Time series plot showing 5-minute instantaneous discharge for Lillooet River](../images/chmn-instantaneous-discharge-ts-plot.png) + *Figure 5: Instantaneous (5-minute) discharge for Lillooet River (CHMN 08MG005)* ### Viewing the Properties Panel @@ -106,14 +111,15 @@ This project contains 6 time series elements, all from the same station: - **Download** button to refresh the data ![Properties panel showing CHMN site number, data type dropdown, and Download button](../images/chmn-properties-panel.png) + *Figure 6: Properties panel for a CHMN time series element* ### Downloading Your Own CHMN Data To create a new CHMN time series element: -1. Right-click **Time Series Data** in the Project Explorer and select **Create New** -2. In the Properties panel, set **Entry Method** to **CHMN** +1. Right-click **Time Series Data** in the Project Explorer and select **New Time Series** +2. After naming the time series, in the Properties panel, set **Entry Method** to **CHMN** 3. Enter a valid **CHMN Station ID** (7 characters, e.g., `08MG005`) 4. Select the desired **Data Type** from the dropdown 5. Click **Download** diff --git a/examples/1-time-series-data/4-abom-download/abom-download-example.bestfit b/examples/1-time-series-data/4-abom-download/abom-download-example.bestfit index a6d41e6..014a49c 100644 Binary files a/examples/1-time-series-data/4-abom-download/abom-download-example.bestfit and b/examples/1-time-series-data/4-abom-download/abom-download-example.bestfit differ diff --git a/examples/1-time-series-data/4-abom-download/abom-download-example.md b/examples/1-time-series-data/4-abom-download/abom-download-example.md index a5e0565..978be23 100644 --- a/examples/1-time-series-data/4-abom-download/abom-download-example.md +++ b/examples/1-time-series-data/4-abom-download/abom-download-example.md @@ -60,16 +60,18 @@ Some daily series from BOM may contain missing data (NaN values). This is common 4. The Project Explorer will show 6 elements under **Time Series Data** ![RMC-BestFit Project Explorer showing all 6 ABOM time series elements](../images/abom-project-explorer.png) + *Figure 1: Project Explorer with all ABOM time series elements* ### Exploring Daily Precipitation (Cotter River) 1. Click **ABOM - 410730 - Daily Precipitation** in the Project Explorer -2. The **Time Series** tab displays the daily rainfall record +2. The **Time Series** tab on the left displays the daily rainfall record 3. Notice the episodic rainfall pattern with occasional high-intensity events -4. Click the **Seasonality** tab to observe the seasonal rainfall distribution +4. Click the **Seasonality** tab on the left to observe the seasonal rainfall distribution ![Time series plot showing daily precipitation for Cotter River at Gingera](../images/abom-precipitation-ts-plot.png) + *Figure 2: Daily precipitation for Cotter River at Gingera, ACT (BOM 410730)* ### Exploring Daily Discharge (Cotter River) @@ -79,6 +81,7 @@ Some daily series from BOM may contain missing data (NaN values). This is common 3. Click the **Seasonality** tab to see the seasonal flow pattern ![Time series plot showing daily discharge for Cotter River with visible data gaps](../images/abom-daily-discharge-ts-plot.png) + *Figure 3: Daily discharge for Cotter River at Gingera, ACT (BOM 410730)* ### Exploring Instantaneous Stage (Murray River) @@ -88,6 +91,7 @@ Some daily series from BOM may contain missing data (NaN values). This is common 3. The Murray River at Tocumwal shows the regulated flow pattern of a major river system ![Time series plot showing instantaneous stage for Murray River at Tocumwal](../images/abom-instantaneous-stage-ts-plot.png) + *Figure 4: Instantaneous water level for Murray River at Tocumwal, NSW (BOM 409202)* ### Viewing the Properties Panel @@ -101,14 +105,15 @@ Some daily series from BOM may contain missing data (NaN values). This is common - **Download** button to refresh the data ![Properties panel showing ABOM site number, data type dropdown, and Download button](../images/abom-properties-panel.png) + *Figure 5: Properties panel for an ABOM time series element* ### Downloading Your Own ABOM Data To create a new ABOM time series element: -1. Right-click **Time Series Data** in the Project Explorer and select **Create New** -2. In the Properties panel, set **Entry Method** to **ABOM** +1. Right-click **Time Series Data** in the Project Explorer and select **New Time Series** +2. After naming the time series, in the Properties panel, set **Entry Method** to **ABOM** 3. Enter a valid **ABOM Station ID** (6 digits, e.g., `410730`) 4. Select the desired **Data Type** from the dropdown 5. For Daily Precipitation, also select the **Depth Unit** (Millimeters, Centimeters, or Inches) diff --git a/examples/1-time-series-data/5-hec-dss-import/hec-dss-import-example.bestfit b/examples/1-time-series-data/5-hec-dss-import/hec-dss-import-example.bestfit index ecd3171..1c0168b 100644 Binary files a/examples/1-time-series-data/5-hec-dss-import/hec-dss-import-example.bestfit and b/examples/1-time-series-data/5-hec-dss-import/hec-dss-import-example.bestfit differ diff --git a/examples/1-time-series-data/5-hec-dss-import/hec-dss-import-example.md b/examples/1-time-series-data/5-hec-dss-import/hec-dss-import-example.md index f04ae1a..72a10a4 100644 --- a/examples/1-time-series-data/5-hec-dss-import/hec-dss-import-example.md +++ b/examples/1-time-series-data/5-hec-dss-import/hec-dss-import-example.md @@ -52,6 +52,7 @@ This dataset represents a reservoir routing simulation for Grapevine Dam (Trinit 4. The Project Explorer will show 2 elements under **Time Series Data** ![RMC-BestFit Project Explorer showing the 2 HEC-DSS time series elements](../images/hec-dss-project-explorer.png) + *Figure 1: Project Explorer with HEC-DSS time series elements* ### Exploring the Inflow Hydrograph @@ -61,6 +62,7 @@ This dataset represents a reservoir routing simulation for Grapevine Dam (Trinit 3. Notice the sharp flood peak followed by a gradual recession ![Time series plot showing the hourly inflow hydrograph for Grapevine Dam](../images/hec-dss-inflow-ts-plot.png) + *Figure 2: Hourly inflow hydrograph for Grapevine Dam* ### Comparing Inflow and Outflow with Alternative Time Series @@ -73,6 +75,7 @@ RMC-BestFit's **Alternative Time Series** feature lets you overlay another time 4. The outflow hydrograph will be overlaid on the inflow plot, visually demonstrating the reservoir's flood attenuation effect ![Time series plot showing inflow and outflow hydrographs overlaid using the Alternative Time Series feature](../images/hec-dss-inflow-outflow-comparison.png) + *Figure 3: Inflow vs. outflow -- the Alternative Time Series feature shows how the reservoir attenuates the flood peak* ### Viewing the Properties Panel @@ -85,20 +88,22 @@ RMC-BestFit's **Alternative Time Series** feature lets you overlay another time - **Import** button to re-import from the DSS file ![Properties panel showing HEC-DSS file path, DSS pathname, and Import button](../images/hec-dss-properties-panel.png) + *Figure 4: Properties panel for a HEC-DSS time series element* ### Importing Your Own HEC-DSS Data To create a new HEC-DSS time series element: -1. Right-click **Time Series Data** in the Project Explorer and select **Create New** -2. In the Properties panel, set **Entry Method** to **HEC-DSS** -3. Click **Browse** to select a `.dss` file -4. The **DSS Path Selector** window will open, displaying all available pathnames in the file -5. Select the desired dataset and click **OK** +1. Right-click **Time Series Data** in the Project Explorer and select **New Time Series** +2. After naming the time series, in the Properties panel, set **Entry Method** to **HEC-DSS** +3. Click the three dots (...) to the right of the **DSS Filename Selector** to browse for a `.dss` file +4. After selecting the `.dss` file, click the three dots (...) to the right of the **DSS Path Selector** and a window will open, displaying all available pathnames in the file +5. Select the desired dataset and click **Set Path** 6. Click **Import** to load the data ![DSS Path Selector window showing available pathnames in the DSS file](../images/hec-dss-path-selector.png) + *Figure 5: DSS Path Selector window -- browse and select datasets from a HEC-DSS file* ## Key Settings diff --git a/examples/1-time-series-data/6-manual-entry/manual-entry-example.bestfit b/examples/1-time-series-data/6-manual-entry/manual-entry-example.bestfit index 870115a..d5f443b 100644 Binary files a/examples/1-time-series-data/6-manual-entry/manual-entry-example.bestfit and b/examples/1-time-series-data/6-manual-entry/manual-entry-example.bestfit differ diff --git a/examples/1-time-series-data/6-manual-entry/manual-entry-example.md b/examples/1-time-series-data/6-manual-entry/manual-entry-example.md index a721ab3..0e2019e 100644 --- a/examples/1-time-series-data/6-manual-entry/manual-entry-example.md +++ b/examples/1-time-series-data/6-manual-entry/manual-entry-example.md @@ -49,6 +49,7 @@ This dataset is commonly used to demonstrate seasonal decomposition, trend-cycle Open `manual-entry-example.bestfit` in RMC-BestFit. The Project Explorer shows three Time Series Data elements: ![Project Explorer showing the three manual entry elements: Airline Passengers, Nile River Flows, and Mauna Loa CO2](../images/manual-entry-project-explorer.png) + *Figure 1: Project Explorer with three manually entered time series* Each element contains the full dataset already entered. Click on any element to view the time series plot and explore its statistical properties. @@ -64,7 +65,7 @@ Each element contains the full dataset already entered. Click on any element to ### Exploring the Time Series Tabs -Click on an element to open it. The main view shows four tabs: +Click on an element to open it. The main view shows four tabs to the left: 1. **Time Series** -- The raw data plotted against time. Look for trend, seasonality, and level shifts. 2. **Seasonality** -- A seasonal subseries plot showing data grouped by month (or other period). Useful for identifying recurring patterns. @@ -72,15 +73,19 @@ Click on an element to open it. The main view shows four tabs: 4. **PACF** -- Partial autocorrelation function. Helps identify AR order -- significant spikes at lags 1 through *p* suggest an AR(*p*) model. ![Time series plot of Airline Passengers showing upward trend with growing seasonal amplitude](../images/manual-entry-airline-ts-plot.png) + *Figure 2: Airline Passengers time series showing multiplicative seasonal pattern* ![ACF plot of Airline Passengers showing slowly decaying autocorrelation with seasonal peaks](../images/manual-entry-airline-acf.png) + *Figure 3: ACF of Airline Passengers -- periodic peaks at lags 12, 24, 36 indicate seasonality* ![Time series plot of Nile River Flows showing level shift around 1898](../images/manual-entry-nile-ts-plot.png) + *Figure 4: Nile River annual flows with visible level shift* ![Time series plot of Mauna Loa CO2 showing upward trend with seasonal cycle](../images/manual-entry-co2-ts-plot.png) + *Figure 5: Mauna Loa CO2 with accelerating trend and annual seasonal cycle* ### Viewing the Properties Panel @@ -93,6 +98,7 @@ Open the Properties panel (click **Properties** in the toolbar or press **F4**) - **Start Date** -- The date of the first observation ![Properties panel showing Entry Method = Manual, Time Interval = One Month, and Unit Label for Airline Passengers](../images/manual-entry-properties.png) + *Figure 6: Properties panel for a manually entered time series* ## Creating Your Own Manual Entry Element @@ -102,7 +108,7 @@ To enter a new time series manually from a CSV file: ### 1. Create the Element 1. Right-click **Time Series Data** in the Project Explorer -2. Select **Create New** +2. Select **New Time Series** 3. Enter a descriptive name for the element ### 2. Configure the Properties diff --git a/examples/1-time-series-data/images/abom-daily-discharge-ts-plot.png b/examples/1-time-series-data/images/abom-daily-discharge-ts-plot.png new file mode 100644 index 0000000..8fd15bf Binary files /dev/null and b/examples/1-time-series-data/images/abom-daily-discharge-ts-plot.png differ diff --git a/examples/1-time-series-data/images/abom-instantaneous-stage-ts-plot.png b/examples/1-time-series-data/images/abom-instantaneous-stage-ts-plot.png new file mode 100644 index 0000000..2cc3494 Binary files /dev/null and b/examples/1-time-series-data/images/abom-instantaneous-stage-ts-plot.png differ diff --git a/examples/1-time-series-data/images/abom-precipitation-ts-plot.png b/examples/1-time-series-data/images/abom-precipitation-ts-plot.png new file mode 100644 index 0000000..3ebc530 Binary files /dev/null and b/examples/1-time-series-data/images/abom-precipitation-ts-plot.png differ diff --git a/examples/1-time-series-data/images/abom-project-explorer.png b/examples/1-time-series-data/images/abom-project-explorer.png new file mode 100644 index 0000000..a417f75 Binary files /dev/null and b/examples/1-time-series-data/images/abom-project-explorer.png differ diff --git a/examples/1-time-series-data/images/abom-properties-panel.png b/examples/1-time-series-data/images/abom-properties-panel.png new file mode 100644 index 0000000..d430765 Binary files /dev/null and b/examples/1-time-series-data/images/abom-properties-panel.png differ diff --git a/examples/1-time-series-data/images/chmn-daily-discharge-seasonality.png b/examples/1-time-series-data/images/chmn-daily-discharge-seasonality.png new file mode 100644 index 0000000..d580121 Binary files /dev/null and b/examples/1-time-series-data/images/chmn-daily-discharge-seasonality.png differ diff --git a/examples/1-time-series-data/images/chmn-daily-discharge-ts-plot.png b/examples/1-time-series-data/images/chmn-daily-discharge-ts-plot.png new file mode 100644 index 0000000..ca3f9a2 Binary files /dev/null and b/examples/1-time-series-data/images/chmn-daily-discharge-ts-plot.png differ diff --git a/examples/1-time-series-data/images/chmn-instantaneous-discharge-ts-plot.png b/examples/1-time-series-data/images/chmn-instantaneous-discharge-ts-plot.png new file mode 100644 index 0000000..b4f687f Binary files /dev/null and b/examples/1-time-series-data/images/chmn-instantaneous-discharge-ts-plot.png differ diff --git a/examples/1-time-series-data/images/chmn-peak-discharge-ts-plot.png b/examples/1-time-series-data/images/chmn-peak-discharge-ts-plot.png new file mode 100644 index 0000000..5a6e4d3 Binary files /dev/null and b/examples/1-time-series-data/images/chmn-peak-discharge-ts-plot.png differ diff --git a/examples/1-time-series-data/images/chmn-project-explorer.png b/examples/1-time-series-data/images/chmn-project-explorer.png new file mode 100644 index 0000000..0a1944c Binary files /dev/null and b/examples/1-time-series-data/images/chmn-project-explorer.png differ diff --git a/examples/1-time-series-data/images/chmn-properties-panel.png b/examples/1-time-series-data/images/chmn-properties-panel.png new file mode 100644 index 0000000..48b6def Binary files /dev/null and b/examples/1-time-series-data/images/chmn-properties-panel.png differ diff --git a/examples/1-time-series-data/images/ghcn-precipitation-seasonality-plot.png b/examples/1-time-series-data/images/ghcn-precipitation-seasonality-plot.png new file mode 100644 index 0000000..bba927e Binary files /dev/null and b/examples/1-time-series-data/images/ghcn-precipitation-seasonality-plot.png differ diff --git a/examples/1-time-series-data/images/ghcn-precipitation-ts-plot.png b/examples/1-time-series-data/images/ghcn-precipitation-ts-plot.png new file mode 100644 index 0000000..cba1add Binary files /dev/null and b/examples/1-time-series-data/images/ghcn-precipitation-ts-plot.png differ diff --git a/examples/1-time-series-data/images/ghcn-project-explorer.png b/examples/1-time-series-data/images/ghcn-project-explorer.png new file mode 100644 index 0000000..78fd7ea Binary files /dev/null and b/examples/1-time-series-data/images/ghcn-project-explorer.png differ diff --git a/examples/1-time-series-data/images/ghcn-properties-panel.png b/examples/1-time-series-data/images/ghcn-properties-panel.png new file mode 100644 index 0000000..20d1fd2 Binary files /dev/null and b/examples/1-time-series-data/images/ghcn-properties-panel.png differ diff --git a/examples/1-time-series-data/images/ghcn-snow-ts-plot.png b/examples/1-time-series-data/images/ghcn-snow-ts-plot.png new file mode 100644 index 0000000..4c69c85 Binary files /dev/null and b/examples/1-time-series-data/images/ghcn-snow-ts-plot.png differ diff --git a/examples/1-time-series-data/images/hec-dss-inflow-outflow-comparison.png b/examples/1-time-series-data/images/hec-dss-inflow-outflow-comparison.png new file mode 100644 index 0000000..f40eb32 Binary files /dev/null and b/examples/1-time-series-data/images/hec-dss-inflow-outflow-comparison.png differ diff --git a/examples/1-time-series-data/images/hec-dss-inflow-ts-plot.png b/examples/1-time-series-data/images/hec-dss-inflow-ts-plot.png new file mode 100644 index 0000000..b6813c7 Binary files /dev/null and b/examples/1-time-series-data/images/hec-dss-inflow-ts-plot.png differ diff --git a/examples/1-time-series-data/images/hec-dss-path-selector.png b/examples/1-time-series-data/images/hec-dss-path-selector.png new file mode 100644 index 0000000..dc6f2ba Binary files /dev/null and b/examples/1-time-series-data/images/hec-dss-path-selector.png differ diff --git a/examples/1-time-series-data/images/hec-dss-project-explorer.png b/examples/1-time-series-data/images/hec-dss-project-explorer.png new file mode 100644 index 0000000..babdf8a Binary files /dev/null and b/examples/1-time-series-data/images/hec-dss-project-explorer.png differ diff --git a/examples/1-time-series-data/images/hec-dss-properties-panel.png b/examples/1-time-series-data/images/hec-dss-properties-panel.png new file mode 100644 index 0000000..b07ede6 Binary files /dev/null and b/examples/1-time-series-data/images/hec-dss-properties-panel.png differ diff --git a/examples/1-time-series-data/images/manual-entry-airline-acf.png b/examples/1-time-series-data/images/manual-entry-airline-acf.png new file mode 100644 index 0000000..ca15b16 Binary files /dev/null and b/examples/1-time-series-data/images/manual-entry-airline-acf.png differ diff --git a/examples/1-time-series-data/images/manual-entry-airline-ts-plot.png b/examples/1-time-series-data/images/manual-entry-airline-ts-plot.png new file mode 100644 index 0000000..707a25a Binary files /dev/null and b/examples/1-time-series-data/images/manual-entry-airline-ts-plot.png differ diff --git a/examples/1-time-series-data/images/manual-entry-co2-ts-plot.png b/examples/1-time-series-data/images/manual-entry-co2-ts-plot.png new file mode 100644 index 0000000..2eae08d Binary files /dev/null and b/examples/1-time-series-data/images/manual-entry-co2-ts-plot.png differ diff --git a/examples/1-time-series-data/images/manual-entry-nile-ts-plot.png b/examples/1-time-series-data/images/manual-entry-nile-ts-plot.png new file mode 100644 index 0000000..637b770 Binary files /dev/null and b/examples/1-time-series-data/images/manual-entry-nile-ts-plot.png differ diff --git a/examples/1-time-series-data/images/manual-entry-project-explorer.png b/examples/1-time-series-data/images/manual-entry-project-explorer.png new file mode 100644 index 0000000..8138505 Binary files /dev/null and b/examples/1-time-series-data/images/manual-entry-project-explorer.png differ diff --git a/examples/1-time-series-data/images/manual-entry-properties.png b/examples/1-time-series-data/images/manual-entry-properties.png new file mode 100644 index 0000000..dde40c5 Binary files /dev/null and b/examples/1-time-series-data/images/manual-entry-properties.png differ diff --git a/examples/1-time-series-data/images/usgs-daily-discharge-seasonality.png b/examples/1-time-series-data/images/usgs-daily-discharge-seasonality.png new file mode 100644 index 0000000..f6f52cb Binary files /dev/null and b/examples/1-time-series-data/images/usgs-daily-discharge-seasonality.png differ diff --git a/examples/1-time-series-data/images/usgs-daily-discharge-ts-plot.png b/examples/1-time-series-data/images/usgs-daily-discharge-ts-plot.png new file mode 100644 index 0000000..55101f3 Binary files /dev/null and b/examples/1-time-series-data/images/usgs-daily-discharge-ts-plot.png differ diff --git a/examples/1-time-series-data/images/usgs-instantaneous-discharge-ts-plot.png b/examples/1-time-series-data/images/usgs-instantaneous-discharge-ts-plot.png new file mode 100644 index 0000000..628f016 Binary files /dev/null and b/examples/1-time-series-data/images/usgs-instantaneous-discharge-ts-plot.png differ diff --git a/examples/1-time-series-data/images/usgs-measured-discharge-ts-plot.png b/examples/1-time-series-data/images/usgs-measured-discharge-ts-plot.png new file mode 100644 index 0000000..424b3da Binary files /dev/null and b/examples/1-time-series-data/images/usgs-measured-discharge-ts-plot.png differ diff --git a/examples/1-time-series-data/images/usgs-peak-discharge-ts-plot.png b/examples/1-time-series-data/images/usgs-peak-discharge-ts-plot.png new file mode 100644 index 0000000..404894e Binary files /dev/null and b/examples/1-time-series-data/images/usgs-peak-discharge-ts-plot.png differ diff --git a/examples/1-time-series-data/images/usgs-project-explorer.png b/examples/1-time-series-data/images/usgs-project-explorer.png new file mode 100644 index 0000000..e5fa326 Binary files /dev/null and b/examples/1-time-series-data/images/usgs-project-explorer.png differ diff --git a/examples/1-time-series-data/images/usgs-properties-panel.png b/examples/1-time-series-data/images/usgs-properties-panel.png new file mode 100644 index 0000000..0888500 Binary files /dev/null and b/examples/1-time-series-data/images/usgs-properties-panel.png differ diff --git a/examples/2-input-data/1-block-maximum/usgs-block-max-example.bestfit b/examples/2-input-data/1-block-maximum/usgs-block-max-example.bestfit index c475abc..16cffc4 100644 Binary files a/examples/2-input-data/1-block-maximum/usgs-block-max-example.bestfit and b/examples/2-input-data/1-block-maximum/usgs-block-max-example.bestfit differ diff --git a/examples/2-input-data/1-block-maximum/usgs-block-max-example.md b/examples/2-input-data/1-block-maximum/usgs-block-max-example.md index b3beea2..ba8b44f 100644 --- a/examples/2-input-data/1-block-maximum/usgs-block-max-example.md +++ b/examples/2-input-data/1-block-maximum/usgs-block-max-example.md @@ -26,6 +26,7 @@ Open `usgs-block-max-example.bestfit` in RMC-BestFit. The Project Explorer shows | USGS - 01134500 - Block Max - Water Year | Input Data | Annual maximum using October--September blocks | ![Project Explorer showing the time series and two block maximum Input Data elements](../images/block-max-project-explorer.png) + *Figure 1: Project Explorer with time series and block maximum elements* ## Step-by-Step Guide @@ -40,25 +41,28 @@ Open `usgs-block-max-example.bestfit` in RMC-BestFit. The Project Explorer shows ### Exploring the Source Time Series 1. Click **USGS - 01134500 - Daily Discharge** in the Project Explorer -2. The **Time Series** tab displays the full daily hydrograph spanning 1947 to present -3. Click the **Seasonality** tab to see the annual cycle -- note the spring snowmelt peak between March and May, which is typical of New England rivers +2. The **Time Series** tab on the left displays the full daily hydrograph spanning 1947 to present +3. Click the **Seasonality** tab on the left to see the annual cycle -- note the spring snowmelt peak between March and May, which is typical of New England rivers ![Daily discharge hydrograph for Moose River at Victory, VT](../images/block-max-daily-discharge.png) + *Figure 2: Daily discharge hydrograph for Moose River at Victory, VT* ### Exploring the Calendar Year Block Maximum 1. Click **USGS - 01134500 - Block Max - Calendar Year** in the Project Explorer -2. The **Chronology** tab shows the extracted annual maximum series plotted against year -3. Click the **Frequency** tab to see the empirical frequency curve (plotting positions) -4. Click the **Seasonality** tab to see when annual maxima occur -- most fall in spring (March--May) -5. The **Density**, **Histogram**, and **Q-Q** tabs provide additional views of the sample distribution -6. The **ACF** and **PACF** tabs show the autocorrelation structure of the annual maximum series +2. The **Chronology** tab at the bottom shows the extracted annual maximum series plotted against year +3. Click the **Frequency** tab at the bottom to see the empirical frequency curve (plotting positions) +4. Click the **Seasonality** tab on the left to see when annual maxima occur -- most fall in spring (March--May) +5. The **Density**, **Histogram**, and **Q-Q** tabs to the left provide additional views of the sample distribution +6. The **ACF** and **PACF** tabs to the left show the autocorrelation structure of the annual maximum series ![Chronology plot of calendar year annual maxima](../images/block-max-calendar-chronology.png) + *Figure 3: Calendar year annual maximum series* ![Frequency plot showing empirical plotting positions](../images/block-max-calendar-frequency.png) + *Figure 4: Empirical frequency curve for calendar year annual maxima* ### Exploring the Water Year Block Maximum @@ -68,6 +72,7 @@ Open `usgs-block-max-example.bestfit` in RMC-BestFit. The Project Explorer shows 3. The water year (October 1 through September 30) is the standard block used in U.S. flood frequency practice because it keeps the winter-spring flood season within a single year ![Chronology plot of water year annual maxima](../images/block-max-wateryear-chronology.png) + *Figure 5: Water year annual maximum series* ### Comparing Calendar Year vs Water Year @@ -90,19 +95,23 @@ The calendar year and water year series will often be identical for stations whe - **Block Function:** Maximum - **Time Block:** Calendar Year or Water Year - **Start Month / End Month:** Defines the custom block boundaries (relevant when Time Block is set to Custom Year) + - **Smoothing:** + - **Plotting Position Parameter:** + - **Threshold Value:** ![Properties panel showing block maximum settings](../images/block-max-properties.png) + *Figure 6: Properties panel for a block maximum Input Data element* ### Creating Your Own Block Maximum Element To create a new block maximum Input Data element: -1. Right-click **Input Data** in the Project Explorer and select **Create New** +1. Right-click **Input Data** in the Project Explorer and select **New Input Data** 2. Enter a descriptive name for the element 3. In the Properties panel: - - Set **Exact Data Method** to **Time Series** - - Select a **Time Series Element** from the dropdown (must already exist in the project) + - Set **Data Entry Method** to **Block Series** + - Select a **Time Series** from the dropdown (must already exist in the project) - Set **Block Function** to **Maximum** (or Minimum, Mean) - Set **Time Block** to **Water Year**, **Calendar Year**, or **Custom Year** - If using Custom Year, set the **Start Month** and **End Month** diff --git a/examples/2-input-data/2-usgs-peak-discharge/usgs-peak-download-example.bestfit b/examples/2-input-data/2-usgs-peak-discharge/usgs-peak-download-example.bestfit index af28f45..aaea821 100644 Binary files a/examples/2-input-data/2-usgs-peak-discharge/usgs-peak-download-example.bestfit and b/examples/2-input-data/2-usgs-peak-discharge/usgs-peak-download-example.bestfit differ diff --git a/examples/2-input-data/2-usgs-peak-discharge/usgs-peak-download-example.md b/examples/2-input-data/2-usgs-peak-discharge/usgs-peak-download-example.md index 03c5bb7..445e48c 100644 --- a/examples/2-input-data/2-usgs-peak-discharge/usgs-peak-download-example.md +++ b/examples/2-input-data/2-usgs-peak-discharge/usgs-peak-download-example.md @@ -30,6 +30,7 @@ Open `usgs-peak-download-example.bestfit` in RMC-BestFit. The Project Explorer s | USGS - 11274500 - Peak Discharge | Orestimba Creek near Newman, CA | 47 of 94 years | Ephemeral stream with many zero/low-flow years | ![Project Explorer showing two USGS peak discharge Input Data elements](../images/peak-download-project-explorer.png) + *Figure 1: Project Explorer with USGS peak discharge elements* ## Step-by-Step Guide @@ -44,27 +45,31 @@ Open `usgs-peak-download-example.bestfit` in RMC-BestFit. The Project Explorer s ### Exploring Moose River (01134500) -- No Low Outliers 1. Click **USGS - 01134500 - Peak Discharge** in the Project Explorer -2. The **Chronology** tab shows the annual peak instantaneous discharge from 1947 to present -3. Click the **Frequency** tab to see the empirical frequency curve -- note the smooth distribution with no obvious breaks or gaps in the lower tail +2. The **Chronology** tab at the bottom shows the annual peak instantaneous discharge from 1947 to present +3. Click the **Frequency** tab at the bottom to see the empirical frequency curve -- note the smooth distribution with no obvious breaks or gaps in the lower tail 4. This station has no MGBT low outliers -- the annual peak flows are consistent year to year, as expected for a perennial stream fed by snowmelt ![Chronology of Moose River annual peak discharge](../images/peak-download-moose-river-chronology.png) + *Figure 2: Moose River annual peak discharge -- no low outliers* ![Frequency plot for Moose River](../images/peak-download-moose-river-frequency.png) + *Figure 3: Empirical frequency curve for Moose River* ### Exploring Orestimba Creek (11274500) -- 47 Low Outliers 1. Click **USGS - 11274500 - Peak Discharge** in the Project Explorer -2. The **Chronology** tab reveals a striking pattern: many years have very low or zero peak flows, while a few years have large flood peaks exceeding 10,000 cfs -3. Click the **Frequency** tab -- note the clear break in the lower tail where the MGBT has identified 47 low outliers +2. The **Chronology** tab at the bottom reveals a striking pattern: many years have very low or zero peak flows, while a few years have large flood peaks exceeding 10,000 cfs +3. Click the **Frequency** tab from the bottom-- note the clear break in the lower tail where the MGBT has identified 47 low outliers 4. The low outliers appear as threshold-censored observations (shown differently from exact observations in the data grid and plots) ![Chronology of Orestimba Creek showing many low/zero flow years](../images/peak-download-orestimba-chronology.png) + *Figure 4: Orestimba Creek annual peak discharge -- note the many low-flow years* ![Frequency plot for Orestimba Creek showing MGBT threshold](../images/peak-download-orestimba-frequency.png) + *Figure 5: Empirical frequency curve for Orestimba Creek with MGBT low outliers* ### Understanding the Multiple Grubbs-Beck Test (MGBT) @@ -83,22 +88,23 @@ The MGBT is a statistical test that identifies anomalously low peaks in the annu 1. With either Input Data element selected, open the **Properties** panel 2. The panel shows the USGS peak discharge configuration: - - **Exact Data Method:** USGS Peak Discharge + - **Data Entry Method:** USGS Peak Discharge - **USGS Site Number:** The 8-digit site identifier - **Use Multiple Grubbs-Beck Test:** Checked (enabled by default) - **Download** button to refresh the data from USGS NWIS ![Properties panel showing USGS peak discharge settings](../images/peak-download-properties.png) + *Figure 6: Properties panel for a USGS peak discharge element* ### Downloading Your Own USGS Peak Data To create a new USGS peak discharge Input Data element: -1. Right-click **Input Data** in the Project Explorer and select **Create New** +1. Right-click **Input Data** in the Project Explorer and select **New Input Data** 2. Enter a descriptive name for the element 3. In the Properties panel: - - Set **Exact Data Method** to **USGS Peak Discharge** + - Set **Data Entry Method** to **USGS Peak Discharge** - Enter a valid **USGS Site Number** (8-15 digits). Look up site numbers at https://waterdata.usgs.gov - Enable or disable the **Use Multiple Grubbs-Beck Test** checkbox 4. Click **Download** diff --git a/examples/2-input-data/3-peaks-over-threshold/ghcn-peaks-over-threshold-example.bestfit b/examples/2-input-data/3-peaks-over-threshold/ghcn-peaks-over-threshold-example.bestfit index 3dfcedd..378cb29 100644 Binary files a/examples/2-input-data/3-peaks-over-threshold/ghcn-peaks-over-threshold-example.bestfit and b/examples/2-input-data/3-peaks-over-threshold/ghcn-peaks-over-threshold-example.bestfit differ diff --git a/examples/2-input-data/3-peaks-over-threshold/ghcn-peaks-over-threshold-example.md b/examples/2-input-data/3-peaks-over-threshold/ghcn-peaks-over-threshold-example.md index 582c8b3..47d3cf5 100644 --- a/examples/2-input-data/3-peaks-over-threshold/ghcn-peaks-over-threshold-example.md +++ b/examples/2-input-data/3-peaks-over-threshold/ghcn-peaks-over-threshold-example.md @@ -24,11 +24,10 @@ Open `ghcn-peaks-over-threshold-example.bestfit` in RMC-BestFit. The Project Exp | Element | Type | Description | |---------|------|-------------| | GHCN-USC00040741-Precipitation | Time Series Data | Daily precipitation from NOAA GHCN | -| GHCH-USC00040741-POT | Input Data | POT series with threshold = 1.0 inch, minimum separation = 5 days | - -> **Note:** The Input Data element name contains a typo ("GHCH" instead of "GHCN"). This is a known issue in the example file that will be corrected in a future release. The element functions correctly despite the name. +| GHCN-USC00040741-POT | Input Data | POT series with threshold = 1.0 inch, minimum separation = 5 days | ![Project Explorer showing time series and POT Input Data elements](../images/ghcn-pot-project-explorer.png) + *Figure 1: Project Explorer with precipitation time series and POT elements* ## Step-by-Step Guide @@ -43,23 +42,26 @@ Open `ghcn-peaks-over-threshold-example.bestfit` in RMC-BestFit. The Project Exp ### Exploring the Source Time Series 1. Click **GHCN-USC00040741-Precipitation** in the Project Explorer -2. The **Time Series** tab displays the full daily precipitation record -- note the episodic nature, with most days recording zero precipitation and occasional large storm events -3. Click the **Seasonality** tab to see the Mediterranean climate pattern: precipitation is concentrated in winter (November--April) with dry summers +2. The **Time Series** tab to the left displays the full daily precipitation record -- note the episodic nature, with most days recording zero precipitation and occasional large storm events +3. Click the **Seasonality** tab to the left to see the Mediterranean climate pattern: precipitation is concentrated in winter (November--April) with dry summers ![Daily precipitation record for Big Bear Lake, CA](../images/ghcn-pot-daily-precipitation.png) + *Figure 2: Daily precipitation at Big Bear Lake -- note the seasonal concentration in winter months* ### Exploring the POT Input Data 1. Click **GHCH-USC00040741-POT** in the Project Explorer -2. The **Chronology** tab shows all extracted storm events plotted against time -3. Click the **Frequency** tab to see the empirical frequency curve -4. Click the **Seasonality** tab to confirm events are concentrated in winter months +2. The **Chronology** tab at the bottom shows all extracted storm events plotted against time +3. Click the **Frequency** tab at the bottom to see the empirical frequency curve +4. Click the **Seasonality** tab from the left to confirm events are concentrated in winter months ![Chronology of POT precipitation events](../images/ghcn-pot-chronology.png) + *Figure 3: Chronology of precipitation events exceeding 1.0 inch* ![Frequency plot of POT precipitation events](../images/ghcn-pot-frequency.png) + *Figure 4: Empirical frequency curve for POT precipitation events* ### Understanding the POT Configuration @@ -93,19 +95,23 @@ As with the streamflow POT example, RMC-BestFit provides three threshold diagnos 2. **Modified Scale Stability Plot** -- The adjusted scale parameter should stabilize above the threshold. 3. **Shape Stability Plot** -- The shape parameter should stabilize above the threshold. +These are under the **POT Diagnostics** tab on the left. The tabs at the bottom will switch between the 3 graphs described above. + ![MRL plot for precipitation threshold selection](../images/ghcn-pot-mrl.png) + *Figure 5: Mean Residual Life plot for precipitation threshold* ### Viewing the Properties Panel 1. With the POT Input Data element selected, open the **Properties** panel 2. The panel shows the POT configuration: - - **Exact Data Method:** Peaks-Over-Threshold Series + - **Data Entry Method:** Peaks-Over-Threshold Series - **Time Series Element:** GHCN-USC00040741-Precipitation - **Threshold:** 1.0 (inches) - - **Min Steps Between Peaks:** 5 (days) + - **Minimum Steps [Between Peaks]:** 5 (days) ![Properties panel showing precipitation POT settings](../images/ghcn-pot-properties.png) + *Figure 6: Properties panel for precipitation POT element* ### Creating Your Own Precipitation POT Element @@ -113,12 +119,12 @@ As with the streamflow POT example, RMC-BestFit provides three threshold diagnos To create a POT element from precipitation data: 1. First, ensure you have a daily precipitation time series element in your project (download from GHCN, ABOM, or enter manually) -2. Right-click **Input Data** in the Project Explorer and select **Create New** +2. Right-click **Input Data** in the Project Explorer and select **New Input Data** 3. In the Properties panel: - - Set **Exact Data Method** to **Peaks-Over-Threshold Series** - - Select the precipitation **Time Series Element** + - Set **Data Entry Method** to **Peaks-Over-Threshold Series** + - Select the precipitation **Time Series** - Set an initial **Threshold** -- for daily precipitation in inches, 0.5--2.0 inches is a typical starting range depending on climate - - Set **Min Steps Between Peaks** to 3--5 days for daily precipitation (shorter than streamflow because precipitation events are more distinct) + - Set **Minimum Steps [Between Peaks]** to 3--5 days for daily precipitation (shorter than streamflow because precipitation events are more distinct) 4. Review the threshold diagnostic plots and adjust as needed **Threshold guidance for precipitation:** diff --git a/examples/2-input-data/3-peaks-over-threshold/usgs-peaks-over-threshold-example.bestfit b/examples/2-input-data/3-peaks-over-threshold/usgs-peaks-over-threshold-example.bestfit index 98f8380..39dd932 100644 Binary files a/examples/2-input-data/3-peaks-over-threshold/usgs-peaks-over-threshold-example.bestfit and b/examples/2-input-data/3-peaks-over-threshold/usgs-peaks-over-threshold-example.bestfit differ diff --git a/examples/2-input-data/3-peaks-over-threshold/usgs-peaks-over-threshold-example.md b/examples/2-input-data/3-peaks-over-threshold/usgs-peaks-over-threshold-example.md index ef23a62..507d99c 100644 --- a/examples/2-input-data/3-peaks-over-threshold/usgs-peaks-over-threshold-example.md +++ b/examples/2-input-data/3-peaks-over-threshold/usgs-peaks-over-threshold-example.md @@ -25,6 +25,7 @@ Open `usgs-peaks-over-threshold-example.bestfit` in RMC-BestFit. The Project Exp | USGS - 11274500 - Peaks-Over-Threshold | Input Data | POT series with threshold = 650 cfs, minimum separation = 5 days | ![Project Explorer showing time series and POT Input Data elements](../images/usgs-pot-project-explorer.png) + *Figure 1: Project Explorer with time series and POT elements* ## Step-by-Step Guide @@ -43,19 +44,22 @@ Open `usgs-peaks-over-threshold-example.bestfit` in RMC-BestFit. The Project Exp 3. Click the **Seasonality** tab to confirm that floods are concentrated in the winter wet season (November--April) ![Daily discharge hydrograph for Orestimba Creek](../images/usgs-pot-daily-discharge.png) + *Figure 2: Daily discharge for Orestimba Creek -- highly episodic, event-driven hydrology* ### Exploring the POT Input Data 1. Click **USGS - 11274500 - Peaks-Over-Threshold** in the Project Explorer -2. The **Chronology** tab shows all 78 extracted peaks plotted against time -3. Click the **Frequency** tab to see the empirical frequency curve of the extracted peaks -4. Click the **Seasonality** tab to see when peaks occur -- concentrated in winter months +2. The **Chronology** tab at the bottom shows all 78 extracted peaks plotted against time +3. Click the **Frequency** tab at thd bottom to see the empirical frequency curve of the extracted peaks +4. Click the **Seasonality** tab to the left to see when peaks occur -- concentrated in winter months ![Chronology of POT events extracted from Orestimba Creek](../images/usgs-pot-chronology.png) + *Figure 3: Chronology of 78 peaks over the 650 cfs threshold* ![Frequency plot of POT events](../images/usgs-pot-frequency.png) + *Figure 4: Empirical frequency curve for POT events* ### Understanding the POT Configuration @@ -73,43 +77,47 @@ The POT extraction uses two key parameters: RMC-BestFit provides three diagnostic plots to help select an appropriate threshold: 1. **MRL (Mean Residual Life) Plot** -- Click the **MRL** tab. This plot shows the mean excess over the threshold as a function of threshold level. A roughly linear relationship above a certain threshold suggests that the Generalized Pareto distribution is a reasonable model for the exceedances. The selected threshold should be in the region where the MRL plot appears approximately linear. - 2. **Modified Scale Stability Plot** -- Click the **Modified Scale** tab. This plot shows the estimated scale parameter (adjusted for threshold) as a function of threshold. The parameter should be roughly constant above an appropriate threshold. - 3. **Shape Stability Plot** -- Click the **Shape** tab. This plot shows the estimated shape parameter as a function of threshold. Like the scale plot, the shape parameter should stabilize above an appropriate threshold. +These are under the **POT Diagnostics** tab on the left. The tabs at the bottom will switch between the 3 graphs described above. + ![MRL plot for threshold selection](../images/usgs-pot-mrl.png) + *Figure 5: Mean Residual Life plot supporting the 650 cfs threshold* ![Modified scale stability plot](../images/usgs-pot-modified-scale.png) + *Figure 6: Modified scale stability plot* ![Shape stability plot](../images/usgs-pot-shape.png) + *Figure 7: Shape stability plot* ### Viewing the Properties Panel 1. With the POT Input Data element selected, open the **Properties** panel 2. The panel shows the POT configuration: - - **Exact Data Method:** Peaks-Over-Threshold Series - - **Time Series Element:** The source daily discharge element + - **Data Entry Method:** Peaks-Over-Threshold Series + - **Time Series:** The source daily discharge element - **Threshold:** 650 (cfs) - - **Min Steps Between Peaks:** 5 (days, matching the daily time interval) + - **Minimum Steps [Between Peaks]:** 5 (days, matching the daily time interval) ![Properties panel showing POT settings](../images/usgs-pot-properties.png) + *Figure 8: Properties panel for a POT Input Data element* ### Creating Your Own POT Element To create a new Peaks-Over-Threshold Input Data element: -1. Right-click **Input Data** in the Project Explorer and select **Create New** +1. Right-click **Input Data** in the Project Explorer and select **New Input Data** 2. Enter a descriptive name for the element 3. In the Properties panel: - - Set **Exact Data Method** to **Peaks-Over-Threshold Series** - - Select a **Time Series Element** from the dropdown + - Set **Data Entry Method** to **Peaks-Over-Threshold Series** + - Select a **Time Series** from the dropdown - Set the **Threshold** value -- start with a value that captures a reasonable number of events per year (typically 1--5 events per year is a good target) - - Set **Min Steps Between Peaks** to ensure independence (5--10 days for daily discharge data) + - Set **Minimum Steps [Between Peaks]** to ensure independence (5--10 days for daily discharge data) 4. Review the threshold diagnostic plots (MRL, Modified Scale, Shape) to confirm your threshold choice 5. Adjust the threshold if the diagnostic plots suggest a different value diff --git a/examples/2-input-data/images/block-max-calendar-chronology.png b/examples/2-input-data/images/block-max-calendar-chronology.png new file mode 100644 index 0000000..18a4a0f Binary files /dev/null and b/examples/2-input-data/images/block-max-calendar-chronology.png differ diff --git a/examples/2-input-data/images/block-max-calendar-frequency.png b/examples/2-input-data/images/block-max-calendar-frequency.png new file mode 100644 index 0000000..4af2378 Binary files /dev/null and b/examples/2-input-data/images/block-max-calendar-frequency.png differ diff --git a/examples/2-input-data/images/block-max-daily-discharge.png b/examples/2-input-data/images/block-max-daily-discharge.png new file mode 100644 index 0000000..55101f3 Binary files /dev/null and b/examples/2-input-data/images/block-max-daily-discharge.png differ diff --git a/examples/2-input-data/images/block-max-project-explorer.png b/examples/2-input-data/images/block-max-project-explorer.png new file mode 100644 index 0000000..f1f1418 Binary files /dev/null and b/examples/2-input-data/images/block-max-project-explorer.png differ diff --git a/examples/2-input-data/images/block-max-properties.png b/examples/2-input-data/images/block-max-properties.png new file mode 100644 index 0000000..31c3a41 Binary files /dev/null and b/examples/2-input-data/images/block-max-properties.png differ diff --git a/examples/2-input-data/images/block-max-wateryear-chronology.png b/examples/2-input-data/images/block-max-wateryear-chronology.png new file mode 100644 index 0000000..59d9f8a Binary files /dev/null and b/examples/2-input-data/images/block-max-wateryear-chronology.png differ diff --git a/examples/2-input-data/images/ghcn-pot-chronology.png b/examples/2-input-data/images/ghcn-pot-chronology.png new file mode 100644 index 0000000..bbed824 Binary files /dev/null and b/examples/2-input-data/images/ghcn-pot-chronology.png differ diff --git a/examples/2-input-data/images/ghcn-pot-daily-precipitation.png b/examples/2-input-data/images/ghcn-pot-daily-precipitation.png new file mode 100644 index 0000000..8d30351 Binary files /dev/null and b/examples/2-input-data/images/ghcn-pot-daily-precipitation.png differ diff --git a/examples/2-input-data/images/ghcn-pot-frequency.png b/examples/2-input-data/images/ghcn-pot-frequency.png new file mode 100644 index 0000000..1697ea6 Binary files /dev/null and b/examples/2-input-data/images/ghcn-pot-frequency.png differ diff --git a/examples/2-input-data/images/ghcn-pot-mrl.png b/examples/2-input-data/images/ghcn-pot-mrl.png new file mode 100644 index 0000000..2b13ad0 Binary files /dev/null and b/examples/2-input-data/images/ghcn-pot-mrl.png differ diff --git a/examples/2-input-data/images/ghcn-pot-project-explorer.png b/examples/2-input-data/images/ghcn-pot-project-explorer.png new file mode 100644 index 0000000..80bd1e5 Binary files /dev/null and b/examples/2-input-data/images/ghcn-pot-project-explorer.png differ diff --git a/examples/2-input-data/images/ghcn-pot-properties.png b/examples/2-input-data/images/ghcn-pot-properties.png new file mode 100644 index 0000000..80c8f8d Binary files /dev/null and b/examples/2-input-data/images/ghcn-pot-properties.png differ diff --git a/examples/2-input-data/images/peak-download-moose-river-chronology.png b/examples/2-input-data/images/peak-download-moose-river-chronology.png new file mode 100644 index 0000000..2cd17ec Binary files /dev/null and b/examples/2-input-data/images/peak-download-moose-river-chronology.png differ diff --git a/examples/2-input-data/images/peak-download-moose-river-frequency.png b/examples/2-input-data/images/peak-download-moose-river-frequency.png new file mode 100644 index 0000000..11b7934 Binary files /dev/null and b/examples/2-input-data/images/peak-download-moose-river-frequency.png differ diff --git a/examples/2-input-data/images/peak-download-orestimba-chronology.png b/examples/2-input-data/images/peak-download-orestimba-chronology.png new file mode 100644 index 0000000..4b80d31 Binary files /dev/null and b/examples/2-input-data/images/peak-download-orestimba-chronology.png differ diff --git a/examples/2-input-data/images/peak-download-orestimba-frequency.png b/examples/2-input-data/images/peak-download-orestimba-frequency.png new file mode 100644 index 0000000..54e5557 Binary files /dev/null and b/examples/2-input-data/images/peak-download-orestimba-frequency.png differ diff --git a/examples/2-input-data/images/peak-download-project-explorer.png b/examples/2-input-data/images/peak-download-project-explorer.png new file mode 100644 index 0000000..11705cf Binary files /dev/null and b/examples/2-input-data/images/peak-download-project-explorer.png differ diff --git a/examples/2-input-data/images/peak-download-properties.png b/examples/2-input-data/images/peak-download-properties.png new file mode 100644 index 0000000..42ff1dc Binary files /dev/null and b/examples/2-input-data/images/peak-download-properties.png differ diff --git a/examples/2-input-data/images/sgs-pot-modified-scale.png b/examples/2-input-data/images/sgs-pot-modified-scale.png new file mode 100644 index 0000000..d7569ba Binary files /dev/null and b/examples/2-input-data/images/sgs-pot-modified-scale.png differ diff --git a/examples/2-input-data/images/usgs-pot-chronology.png b/examples/2-input-data/images/usgs-pot-chronology.png new file mode 100644 index 0000000..085c9f8 Binary files /dev/null and b/examples/2-input-data/images/usgs-pot-chronology.png differ diff --git a/examples/2-input-data/images/usgs-pot-daily-discharge.png b/examples/2-input-data/images/usgs-pot-daily-discharge.png new file mode 100644 index 0000000..082fc2d Binary files /dev/null and b/examples/2-input-data/images/usgs-pot-daily-discharge.png differ diff --git a/examples/2-input-data/images/usgs-pot-frequency.png b/examples/2-input-data/images/usgs-pot-frequency.png new file mode 100644 index 0000000..df480bd Binary files /dev/null and b/examples/2-input-data/images/usgs-pot-frequency.png differ diff --git a/examples/2-input-data/images/usgs-pot-modified-scale.png b/examples/2-input-data/images/usgs-pot-modified-scale.png new file mode 100644 index 0000000..d7569ba Binary files /dev/null and b/examples/2-input-data/images/usgs-pot-modified-scale.png differ diff --git a/examples/2-input-data/images/usgs-pot-mrl.png b/examples/2-input-data/images/usgs-pot-mrl.png new file mode 100644 index 0000000..44edb53 Binary files /dev/null and b/examples/2-input-data/images/usgs-pot-mrl.png differ diff --git a/examples/2-input-data/images/usgs-pot-project-explorer.png b/examples/2-input-data/images/usgs-pot-project-explorer.png new file mode 100644 index 0000000..0943b1b Binary files /dev/null and b/examples/2-input-data/images/usgs-pot-project-explorer.png differ diff --git a/examples/2-input-data/images/usgs-pot-properties.png b/examples/2-input-data/images/usgs-pot-properties.png new file mode 100644 index 0000000..7e80c91 Binary files /dev/null and b/examples/2-input-data/images/usgs-pot-properties.png differ diff --git a/examples/2-input-data/images/usgs-pot-shape.png b/examples/2-input-data/images/usgs-pot-shape.png new file mode 100644 index 0000000..27ac92a Binary files /dev/null and b/examples/2-input-data/images/usgs-pot-shape.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/1-information-expansion/README.txt b/examples/4-univariate-distribution-analysis/1-univariate-analysis/1-information-expansion/README.txt deleted file mode 100644 index e7f537e..0000000 --- a/examples/4-univariate-distribution-analysis/1-univariate-analysis/1-information-expansion/README.txt +++ /dev/null @@ -1,11 +0,0 @@ -Blakely Mountain Dam Example: - --This example follows the workflow provided in the Quick Start User Guide for version 1.0. --The dataset includes systematic data, historical data dating back to 1870, and paleoflood information extending back 5,000 years. --The skew prior is set using regional skew information from the USGS. --Quantile priors are established based on stochastic rainfall-runoff data. - -Viglione et al. 2013 Example: - --This example follows the methodology outlined by Viglione et al. (2013) and is also included in the RMC-BestFit Verification Report for version 1.0. --It includes a comparison with Evdbayes using 3 quantile priors and utilizes the Kamp at Zwettl dataset from 1951–2001, as detailed in Viglione et al. (2013). \ No newline at end of file diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/1-information-expansion/blakely-mountain-dam-bayesian.md b/examples/4-univariate-distribution-analysis/1-univariate-analysis/1-information-expansion/blakely-mountain-dam-bayesian.md deleted file mode 100644 index 0ed63b2..0000000 --- a/examples/4-univariate-distribution-analysis/1-univariate-analysis/1-information-expansion/blakely-mountain-dam-bayesian.md +++ /dev/null @@ -1,107 +0,0 @@ -# blakely-mountain-dam-bayesian - -## Overview - -Bayesian flood frequency analysis for inflows to Blakely Mountain Dam, Arkansas. Demonstrates information expansion using systematic, historical, and paleoflood records with the Log-Pearson Type III distribution. - -## What's Inside - -### Input Data - -| Element | Description | -|---|---| -| `Input Data_1` | Annual peak inflow series for Blakely Mountain Dam, Arkansas — placeholder element to be populated with the systematic + historical + paleoflood record. | - -## Step-by-Step Walkthrough - -### Opening the Project - -1. Open RMC-BestFit 2.0. -2. Select **File > Open** and navigate to `examples/4-univariate-distribution-analysis/1-univariate-analysis/1-information-expansion/`. -3. Open `blakely-mountain-dam-bayesian.bestfit`. - -### Exploring the Elements - -For each Univariate Distribution alternative: - -1. Click the alternative in the Project Explorer. -2. Open the **Frequency** tab to view the AEP-vs-quantile plot. -3. Open the **Markov Chain Trace** tab to confirm chain mixing (well-mixed traces look like fuzzy caterpillars). -4. Open the **Autocorrelation** tab to check effective sample size. -5. Inspect the **Properties** panel for sampler settings (iterations, warmup, point estimator, credible-interval width). - -## Analysis Settings - -Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any alternative to inspect: - -- **Sampler type** (DEMCzs, ARWMH, HMC). -- **Iterations / Warm-up Iterations** — total post-warmup samples per chain. -- **Number of Chains** — typically 6 for routine work. -- **Thinning Interval** — keeps every Nth sample to reduce storage / autocorrelation. -- **Point Estimator** — Posterior Mean (default), Posterior Median, or Posterior Mode (MAP). -- **Credible Interval Width** — typically 0.90 or 0.95. - -## Expected Results - - - -### Parameter Estimates - - - -| Alternative | Parameter | Mean | Median | Lower CI | Upper CI | R-hat | ESS | -|---|---|---|---|---|---|---|---| -| _(placeholder)_ | | | | | | | | - -### Frequency / Quantile Table - - - -| AEP (%) | Return Period (yr) | Median | Lower CI | Upper CI | -|---|---|---|---|---| -| 50 | 2 | | | | -| 10 | 10 | | | | -| 1 | 100 | | | | -| 0.5 | 200 | | | | -| 0.2 | 500 | | | | - -### Plots - -![Frequency curve (AEP versus quantile) for each alternative, with the credible band.](images/blakely-mountain-dam-bayesian-frequency.png) -*Figure: Frequency curve (AEP versus quantile) for each alternative, with the credible band.* - -![Posterior kernel density for each parameter.](images/blakely-mountain-dam-bayesian-kernel-density.png) -*Figure: Posterior kernel density for each parameter.* - -![Markov-chain traces for each parameter.](images/blakely-mountain-dam-bayesian-trace.png) -*Figure: Markov-chain traces for each parameter.* - -![Autocorrelation function of the chains, used to estimate effective sample size.](images/blakely-mountain-dam-bayesian-autocorrelation.png) -*Figure: Autocorrelation function of the chains, used to estimate effective sample size.* - -### MCMC Diagnostics - -Verify chain convergence before interpreting any results: - -- **R-hat** — should be < 1.01 for every parameter. -- **Effective Sample Size (ESS)** — at least a few hundred per parameter. -- **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). -- **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. - -## Next Steps - -- Compare alternatives via the **Bayesian Model Average** element to combine results from multiple distributions. -- Compute **return-period quantiles** (1%, 0.5%, 0.2% AEP) from the frequency-curve table. -- Re-run with informative **quantile priors** if engineering judgment suggests specific upper-bound flood magnitudes. -- Cross-check the LP-III fit against a **Bulletin 17C** fit on the same input data. - -## References - - - ---- - -_This tutorial was generated from the project's `.bestfit` file metadata. The narrative and figure / table sections are placeholders — capture screenshots from the BestFit GUI and paste output tables to complete the guide._ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/1-information-expansion/viglione-et-al-2013.bestfit b/examples/4-univariate-distribution-analysis/1-univariate-analysis/1-information-expansion/viglione-et-al-2013.bestfit index c6030a4..338bb70 100644 Binary files a/examples/4-univariate-distribution-analysis/1-univariate-analysis/1-information-expansion/viglione-et-al-2013.bestfit and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/1-information-expansion/viglione-et-al-2013.bestfit differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/1-information-expansion/viglione-et-al-2013.md b/examples/4-univariate-distribution-analysis/1-univariate-analysis/1-information-expansion/viglione-et-al-2013.md index cd4d23d..aaeff0c 100644 --- a/examples/4-univariate-distribution-analysis/1-univariate-analysis/1-information-expansion/viglione-et-al-2013.md +++ b/examples/4-univariate-distribution-analysis/1-univariate-analysis/1-information-expansion/viglione-et-al-2013.md @@ -48,17 +48,19 @@ Replicates the systematic, temporal-expansion, and causal-information examples f ### Exploring the Elements -For each Univariate Distribution alternative: +For each Univariate Distribution analyis: -1. Click the alternative in the Project Explorer. -2. Open the **Frequency** tab to view the AEP-vs-quantile plot. -3. Open the **Markov Chain Trace** tab to confirm chain mixing (well-mixed traces look like fuzzy caterpillars). -4. Open the **Autocorrelation** tab to check effective sample size. -5. Inspect the **Properties** panel for sampler settings (iterations, warmup, point estimator, credible-interval width). +1. Click the anlaysis in the Project Explorer. +2. The **Distirbution Results** tab to the left shoudld automatically open. Navigate to the **Frequency** tab to view the AEP-vs-quantile plot. +3. Open the **Markov Chain Traces** tab on the left to confirm chain mixing (well-mixed traces look like fuzzy caterpillars). +4. Open the **Autocorrelation** tab on the left to check effective sample size. +5. Inspect the **Properties** panel on the right for sampler settings (iterations, warmup, point estimator, credible-interval width). + +These will be explored more below in the Expected results section. ## Analysis Settings -Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any alternative to inspect: +Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any analysis to inspect: - **Sampler type** (DEMCzs, ARWMH, HMC). - **Iterations / Warm-up Iterations** — total post-warmup samples per chain. @@ -69,65 +71,89 @@ Each Bayesian analysis in this project uses the DEMCzs sampler with project-spec ## Expected Results - +Below are the expected results for Univariate Distribution Analysis labeled "MCMC - Systematic (1995 - 2001)"; this should be the first analysis in the list. +Be sure to explore all of the analyses provided! ### Parameter Estimates +The parameter estimates are found under the **MCMC Report** tab to the left as parameter summary statistics. - - -| Alternative | Parameter | Mean | Median | Lower CI | Upper CI | R-hat | ESS | +| Parameter | Mean | Std Dev | 5% | Median | 95% |R-hat | ESS | |---|---|---|---|---|---|---|---| -| _(placeholder)_ | | | | | | | | +| Location (ξ) | 42.8714 | 3.3179 | 37.4957 | 42.7888 | 48.4046 | 1.0000 | 9171 | +| Scale (α) | 21.1847 | 2.70008 | 17.102 | 20.9951 | 25.8941 | 0.9999 | 9336 | +| Shape (κ) | -0.119352 | 0.129605 | -0.347584 | -0.107699 | 0.0746618 | 1.0002 | 9891 | ### Frequency / Quantile Table +While in the **Distribution Results** tab to the left, select Tabular Results to see the frequency plot's value at each return level probability, - - -| AEP (%) | Return Period (yr) | Median | Lower CI | Upper CI | +| Probability | 95.0% CI | 5.0% CI | Posterior Predictive| Posterior Mean | |---|---|---|---|---| -| 50 | 2 | | | | -| 10 | 10 | | | | -| 1 | 100 | | | | -| 0.5 | 200 | | | | -| 0.2 | 500 | | | | +| 1E-06 | 7249.176548828858 | 237.54234615755306 | 8390.690759368497 | 788.5930275814509 | +| 2E-06 | 5705.736416643618 | 231.49970381965838 | 5668.775898832316 | 715.2902545320234 | +| 5E-06 | 4134.750133527632 | 223.15198402836 | 3466.1612847573515 | 627.2443151845657 | +| 1E-05 | 3262.805726910052 | 216.50974349623468 | 2438.3068758722948 | 566.7523243585697 | +| 2E-05 | 2579.6089061769007 | 209.81963743427042 | 1746.0383177683632 | 511.06316645094137 | +| 5E-05 | 1872.8857357208667 | 200.04291835368343 | 1153.7815035730528 | 444.1729355447143 | +| 0.0001 | 1475.2532905445878 | 192.27252515413468 | 860.5981933961027 | 398.21526477980336 | +| 0.0002 | 1156.5279016580841 | 184.30870430613777 | 653.0555082255905 | 355.9052535325247 | +| 0.0005 | 836.018630415943 | 172.56666960307558 | 465.09924810101097 | 305.0815429201984 | +| 0.001 | 654.8655313176822 | 163.29167230899745 | 366.5306999472315 | 270.1571063577628 | +| 0.002 | 511.66874024571604 | 153.38936412546704 | 293.2095483007016 | 237.99545883063502 | +| 0.005 | 367.7219653043677 | 139.05424038588217 | 222.93011315633413 | 199.33434770123495 | +| 0.01 | 285.78720750480903 | 127.46298159393109 | 183.5628680112678 | 172.72592896638844 | +| 0.02 | 220.96432159683343 | 115.31563330823505 | 152.29151249747403 | 148.15155180033372 | +| 0.05 | 155.93324453677647 | 97.78605649867892 | 119.07572149349717 | 118.39058694741834 | +| 0.1 | 118.86430603517661 | 83.5002137676054 | 97.60306503667266 | 97.56077359456074 | +| 0.2 | 89.4684085584898 | 67.97670971704888 | 77.62314039720046 | 77.66905445312321 | +| 0.3 | 74.91188737933767 | 58.17930829986319 | 66.06015423494782 | 66.11185111368104 | +| 0.5 | 57.23605016683286 | 44.65421612174257 | 50.694071426543566 | 50.80823064916835 | +| 0.7 | 44.15409817301191 | 33.97676379270088 | 38.81336731201928 | 38.98224500624102 | +| 0.8 | 37.76183858420439 | 28.396287065632137 | 32.88665728961099 | 33.070936233524165 | +| 0.9 | 30.518877484249863 | 20.856390137718 | 25.86150386272506 | 26.053676228172517 | +| 0.95 | 25.746206462508045 | 14.955666197182342 | 20.78341382834486 | 21.085444342833004 | +| 0.98 | 21.424981348478372 | 8.422376044223254 | 15.470855064508827 | 16.20403514641554 | +| 0.99 | 19.092326436429126 | 4.414411150570132 | 11.951552128180449 | 13.295883772014633 | ### Plots +There are also plenty of plots to explore our results with. Under the **Distribution Results** tab we have a frequency curve. + +![Frequency curve (AEP versus quantile), with the credible band.](../images/viglione-et-al-2013-frequency.png) + +*Figure 1: Frequency curve (AEP versus quantile), with the credible band.* + +The **Kernal Density** tab shows an estimate for the pdf of each parameter. + +![Posterior kernel density for location parameter (ξ).](../images/viglione-et-al-2013-kernel-density-location.png) + +*Figure 2: Posterior kernel density for location parameter (ξ).* + +The **Markov Chain Traces** tab explores the traces of each Markov chain as it explores the posterior space in order to converge. -![Frequency curve (AEP versus quantile) for each alternative, with the credible band.](images/viglione-et-al-2013-frequency.png) -*Figure: Frequency curve (AEP versus quantile) for each alternative, with the credible band.* +![Markov-chain traces for location parameter (ξ).](../images/viglione-et-al-2013-trace-location.png) -![Posterior kernel density for each parameter.](images/viglione-et-al-2013-kernel-density.png) -*Figure: Posterior kernel density for each parameter.* +*Figure 3: Markov-chain trace for location parameter (ξ).* -![Markov-chain traces for each parameter.](images/viglione-et-al-2013-trace.png) -*Figure: Markov-chain traces for each parameter.* +Finally, we can investigate the autocorrelation of the chains under the **Autocorrelation** tab. -![Autocorrelation function of the chains, used to estimate effective sample size.](images/viglione-et-al-2013-autocorrelation.png) -*Figure: Autocorrelation function of the chains, used to estimate effective sample size.* +![Autocorrelation function of the chains, used to estimate effective sample size, for location parameter (ξ).](../images/viglione-et-al-2013-autocorrelation-location.png) + +*Figure 4: Autocorrelation function of the chains, used to estimate effective sample size, for location parameter (ξ).* ### MCMC Diagnostics -Verify chain convergence before interpreting any results: +One should always verify chain convergence before interpreting any results. There are a variety of ways including: - **R-hat** — should be < 1.01 for every parameter. - **Effective Sample Size (ESS)** — at least a few hundred per parameter. - **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). - **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. -## Next Steps +These can be found under the **Markov Chain Traces** and **MCMC Reports** tabs. -- Compare alternatives via the **Bayesian Model Average** element to combine results from multiple distributions. +## Next Steps +- Compare analyses via the **Bayesian Model Average** element to combine results from multiple distributions. + - Right click the **Univariate Distribution Analysis** drop down and select "New Composite Distribution Analysis" + - Select from the available options in the **Properties** panel to the right - Compute **return-period quantiles** (1%, 0.5%, 0.2% AEP) from the frequency-curve table. - Re-run with informative **quantile priors** if engineering judgment suggests specific upper-bound flood magnitudes. -- Cross-check the LP-III fit against a **Bulletin 17C** fit on the same input data. - -## References - - - ---- - -_This tutorial was generated from the project's `.bestfit` file metadata. The narrative and figure / table sections are placeholders — capture screenshots from the BestFit GUI and paste output tables to complete the guide._ +- Cross-check the LP-III fit against a **Bulletin 17C** fit on the same input data. \ No newline at end of file diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/2-arr-flike/README.txt b/examples/4-univariate-distribution-analysis/1-univariate-analysis/2-arr-flike/README.txt deleted file mode 100644 index 0b18523..0000000 --- a/examples/4-univariate-distribution-analysis/1-univariate-analysis/2-arr-flike/README.txt +++ /dev/null @@ -1,3 +0,0 @@ -ARR-FLIKE Examples: - --This example follows the methodology provided by Australian Rainfall and Runoff using the Flike software, as included in the RMC-BestFit Verification Report for version 1.0. diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/2-arr-flike/arr-flike-examples.bestfit b/examples/4-univariate-distribution-analysis/1-univariate-analysis/2-arr-flike/arr-flike-examples.bestfit index 90d3874..93bf776 100644 Binary files a/examples/4-univariate-distribution-analysis/1-univariate-analysis/2-arr-flike/arr-flike-examples.bestfit and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/2-arr-flike/arr-flike-examples.bestfit differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/2-arr-flike/arr-flike-examples.md b/examples/4-univariate-distribution-analysis/1-univariate-analysis/2-arr-flike/arr-flike-examples.md index 42bcd65..9431044 100644 --- a/examples/4-univariate-distribution-analysis/1-univariate-analysis/2-arr-flike/arr-flike-examples.md +++ b/examples/4-univariate-distribution-analysis/1-univariate-analysis/2-arr-flike/arr-flike-examples.md @@ -3,6 +3,7 @@ ## Overview Bayesian replication of the Australian Rainfall and Runoff (ARR) flood-frequency worked examples. Demonstrates the LP-III distribution applied to systematic, censored, and historical flood records following the FLIKE software conventions. +These examples follows the methodology provided by Australian Rainfall and Runoff using the Flike software, as included in the RMC-BestFit Verification Report for version 1.0. ## What's Inside @@ -45,17 +46,19 @@ Bayesian replication of the Australian Rainfall and Runoff (ARR) flood-frequency ### Exploring the Elements -For each Univariate Distribution alternative: +For each Univariate Distribution anlysis: -1. Click the alternative in the Project Explorer. -2. Open the **Frequency** tab to view the AEP-vs-quantile plot. -3. Open the **Markov Chain Trace** tab to confirm chain mixing (well-mixed traces look like fuzzy caterpillars). -4. Open the **Autocorrelation** tab to check effective sample size. -5. Inspect the **Properties** panel for sampler settings (iterations, warmup, point estimator, credible-interval width). +1. Click the analysis in the Project Explorer. +2. The **Distirbution Results** tab to the left shoudld automatically open. Navigate to the **Frequency** tab to view the AEP-vs-quantile plot. +3. Open the **Markov Chain Traces** tab on the left to confirm chain mixing (well-mixed traces look like fuzzy caterpillars). +4. Open the **Autocorrelation** tab on the left to check effective sample size. +5. Inspect the **Properties** panel on the right for sampler settings (iterations, warmup, point estimator, credible-interval width). + +These will be explored more below in the Expected results section. ## Analysis Settings -Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any alternative to inspect: +Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel to the right of any analysis to inspect: - **Sampler type** (DEMCzs, ARWMH, HMC). - **Iterations / Warm-up Iterations** — total post-warmup samples per chain. @@ -65,66 +68,90 @@ Each Bayesian analysis in this project uses the DEMCzs sampler with project-spec - **Credible Interval Width** — typically 0.90 or 0.95. ## Expected Results - - +Below are the expected results for Univariate Distribution Analysis labeled "Example #3"; this should be the first analysis in the list. +Be sure to explore all of the analyses provided! ### Parameter Estimates +The parameter estimates are found under the **MCMC Report** tab to the left as parameter summary statistics. - - -| Alternative | Parameter | Mean | Median | Lower CI | Upper CI | R-hat | ESS | +| Parameter | Mean | Std Dev | 5% | Median | 95% |R-hat | ESS | |---|---|---|---|---|---|---|---| -| _(placeholder)_ | | | | | | | | +| Mean (of log) (µ) | 2.79105 | 0.115766 | 2.60569| 2.78975 | 2.98087 | 1.0001 | 9161 | +| Std Dev (of log) (σ) | 0.625022 | 0.0944821 | 0.494548 | 0.613411 | 0.793603 | 0.9999 | 8792 | +| Skew (of log) (γ) | 0.117887 | 0.479936 | -0.647196 | 0.105425 | 0.916886 | 0.9998 | 8474 | ### Frequency / Quantile Table +While in the **Distribution Results** tab to the left, select Tabular Results to see the frequency plot's value at each return level probability, - - -| AEP (%) | Return Period (yr) | Median | Lower CI | Upper CI | +| Probability | 95.0% CI | 5.0% CI | Posterior Predictive| Posterior Mean | |---|---|---|---|---| -| 50 | 2 | | | | -| 10 | 10 | | | | -| 1 | 100 | | | | -| 0.5 | 200 | | | | -| 0.2 | 500 | | | | +| 1E-06 | 507894873.72939694 | 31400.078902128 | 28240390327.448273 | 1075113.0276012735 | +| 2E-06 | 276498072.0650721 | 29703.731020245366 | 4178308800.2617283 | 843070.6337592058 | +| 5E-06 | 123143469.32011892 | 27446.509484261216 | 468992685.5418231 | 605824.2507058325 | +| 1E-05 | 66897069.18047385 | 25785.637852707303 | 113467310.2610285 | 468273.54718754545 | +| 2E-05 | 36110754.31549659 | 23960.6771624511 | 32503412.322293572 | 359351.65119201073 | +| 5E-05 | 15490445.31614817 | 21533.357889403625 | 7655298.062862985 | 250120.05487908743 | +| 0.0001 | 8194152.477189892 | 19763.849546885987 | 2900441.373266232 | 188156.07098303808 | +| 0.0002 | 4313801.305197655 | 17889.172856339643 | 1196930.0344285506 | 140086.57779670059 | +| 0.0005 | 1808397.596807069 | 15415.097597258653 |413730.23095646885 | 93128.56376379418 | +| 0.001 | 935210.4917356665 | 13490.83667465741 | 198574.1128616403 | 67286.61199721164 | +| 0.002 | 481340.9695161464 | 11421.750844987131 | 100359.01765326156 | 47818.47878708741 | +| 0.005 | 196545.8043277691 | 8967.912598595607 | 43682.00991930671 | 29519.941628798613 | +| 0.01 | 97540.94370518686 | 7143.213278992808 | 24396.56901115398 | 19907.0627403773 | +| 0.02 | 47267.37407231437 | 5454.21743072416 | 14080.975182438142 | 12997.168821870711 | +| 0.05 | 17711.242944315694 | 3447.045402600443 | 6950.820553226646 | 6912.468882893855 | +| 0.1 | 8033.157444202306 | 2205.4649474226485 | 3944.4710282473447 | 3976.6793706847543 | +| 0.2 | 3531.667258731276 | 1235.542928477663 | 2044.9496448434477 | 2056.7470089856315 | +| 0.3 | 2099.5519839106696 | 797.0496176357684 | 1283.7201345980825 | 1287.3508688852967 | +| 0.5 | 953.5864424919969 | 378.1418507798334 | 599.9661367871256 | 600.8571704801963 | +| 0.7 | 456.1352344190664 | 178.38187411251013 | 284.578089119132 | 284.83869585941505 | +| 0.8 | 298.46299667716636 | 111.14612101564778 | 183.0319428884676 | 182.70759329641467 | +| 0.9 | 170.79926405224717 | 53.23615358318095 | 100.37478638288647 | 99.62163322187797 | +| 0.95 | 113.02739780461646 | 26.612825620081423 | 61.037092310896966 | 60.862042588817005 | +| 0.98 | 75.38460109045634 | 11.557231103937012 | 33.158380600761035 | 35.25834219121622 | +| 0.99 | 60.3582851999637 | 6.436732082882738 | 20.60363776336522 | 24.62723628788043 | + ### Plots +There are also plenty of plots to explore our results with. Under the **Distribution Results** tab we have a frequency curve. + +![Frequency curve (AEP versus quantile), with the credible band.](../images/arr-flike-examples-frequency.png) + +*Figure 1: Frequency curve (AEP versus quantile), with the credible band.* + +The **Kernal Density** tab shows an estimate for the pdf of each parameter. + +![Posterior kernel density for mean parameter (µ).](../images/arr-flike-examples-kernel-density-mean.png) + +*Figure 2: Posterior kernel density for mean parameter (µ).* -![Frequency curve (AEP versus quantile) for each alternative, with the credible band.](images/arr-flike-examples-frequency.png) -*Figure: Frequency curve (AEP versus quantile) for each alternative, with the credible band.* +The **Markov Chain Traces** tab explores the traces of each Markov chain as it explores the posterior space in order to converge. -![Posterior kernel density for each parameter.](images/arr-flike-examples-kernel-density.png) -*Figure: Posterior kernel density for each parameter.* +![Markov-chain traces for mean parameter (µ).](../images/arr-flike-examples-trace-mean.png) -![Markov-chain traces for each parameter.](images/arr-flike-examples-trace.png) -*Figure: Markov-chain traces for each parameter.* +*Figure 3: Markov-chain traces for mean parameter (µ).* -![Autocorrelation function of the chains, used to estimate effective sample size.](images/arr-flike-examples-autocorrelation.png) -*Figure: Autocorrelation function of the chains, used to estimate effective sample size.* +Finally, we can investigate the autocorrelation of the chains under the **Autocorrelation** tab. + +![Autocorrelation function of the chains, used to estimate effective sample size, for mean parameter (µ).](../images/arr-flike-examples-autocorrelation-mean.png) + +*Figure 4: Autocorrelation function of the chains, used to estimate effective sample size, for mean parameter (µ).* ### MCMC Diagnostics -Verify chain convergence before interpreting any results: +One should always verify chain convergence before interpreting any results. There are a variety of ways including: - **R-hat** — should be < 1.01 for every parameter. - **Effective Sample Size (ESS)** — at least a few hundred per parameter. - **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). - **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. -## Next Steps +These can be found under the **Markov Chain Traces** and **MCMC Reports** tabs. -- Compare alternatives via the **Bayesian Model Average** element to combine results from multiple distributions. +## Next Steps +- Compare analyses via the **Bayesian Model Average** element to combine results from multiple distributions. + - Right click the **Univariate Distribution Analysis** drop down and select "New Composite Distribution Analysis" + - Select from the available options in the **Properties** panel to the right - Compute **return-period quantiles** (1%, 0.5%, 0.2% AEP) from the frequency-curve table. - Re-run with informative **quantile priors** if engineering judgment suggests specific upper-bound flood magnitudes. -- Cross-check the LP-III fit against a **Bulletin 17C** fit on the same input data. - -## References - - - ---- - -_This tutorial was generated from the project's `.bestfit` file metadata. The narrative and figure / table sections are placeholders — capture screenshots from the BestFit GUI and paste output tables to complete the guide._ +- Cross-check the LP-III fit against a **Bulletin 17C** fit on the same input data. \ No newline at end of file diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/3-bulletin17C-examples/bulletin-17c-bayesian-examples.bestfit b/examples/4-univariate-distribution-analysis/1-univariate-analysis/3-bulletin17C-examples/bulletin-17c-bayesian-examples.bestfit index c4ff7db..9d1d5f7 100644 Binary files a/examples/4-univariate-distribution-analysis/1-univariate-analysis/3-bulletin17C-examples/bulletin-17c-bayesian-examples.bestfit and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/3-bulletin17C-examples/bulletin-17c-bayesian-examples.bestfit differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/3-bulletin17C-examples/bulletin-17c-bayesian-examples.md b/examples/4-univariate-distribution-analysis/1-univariate-analysis/3-bulletin17C-examples/bulletin-17c-bayesian-examples.md index 3dd62b0..599e6cf 100644 --- a/examples/4-univariate-distribution-analysis/1-univariate-analysis/3-bulletin17C-examples/bulletin-17c-bayesian-examples.md +++ b/examples/4-univariate-distribution-analysis/1-univariate-analysis/3-bulletin17C-examples/bulletin-17c-bayesian-examples.md @@ -52,17 +52,19 @@ Bayesian re-fits of the seven Bulletin 17C example datasets (Moose River, Oresti ### Exploring the Elements -For each Univariate Distribution alternative: +For each Univariate Distribution anlysis: -1. Click the alternative in the Project Explorer. -2. Open the **Frequency** tab to view the AEP-vs-quantile plot. -3. Open the **Markov Chain Trace** tab to confirm chain mixing (well-mixed traces look like fuzzy caterpillars). -4. Open the **Autocorrelation** tab to check effective sample size. -5. Inspect the **Properties** panel for sampler settings (iterations, warmup, point estimator, credible-interval width). +1. Click the analysis in the Project Explorer. +2. The **Distirbution Results** tab to the left shoudld automatically open. Navigate to the **Frequency** tab to view the AEP-vs-quantile plot. +3. Open the **Markov Chain Traces** tab on the left to confirm chain mixing (well-mixed traces look like fuzzy caterpillars). +4. Open the **Autocorrelation** tab on the left to check effective sample size. +5. Inspect the **Properties** panel on the right for sampler settings (iterations, warmup, point estimator, credible-interval width). + +These will be explored more below in the Expected results section. ## Analysis Settings -Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any alternative to inspect: +Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel to the right of any analysis to inspect: - **Sampler type** (DEMCzs, ARWMH, HMC). - **Iterations / Warm-up Iterations** — total post-warmup samples per chain. @@ -72,66 +74,90 @@ Each Bayesian analysis in this project uses the DEMCzs sampler with project-spec - **Credible Interval Width** — typically 0.90 or 0.95. ## Expected Results - - +Below are the expected results for Univariate Distribution Analysis labeled "Bayes Example #1"; this should be the first analysis in the list. +Be sure to explore all of the analyses provided! ### Parameter Estimates - +The parameter estimates are found under the **MCMC Report** tab to the left as parameter summary statistics. -| Alternative | Parameter | Mean | Median | Lower CI | Upper CI | R-hat | ESS | +| Parameter | Mean | Std Dev | 5% | Median | 95% |R-hat | ESS | |---|---|---|---|---|---|---|---| -| _(placeholder)_ | | | | | | | | +| Mean (of log) (µ) | 3.32903 | 0.017966 | 3.30022 | 3.32859 | 3.35871 | 0.9998 | 9300 | +| Std Dev (of log) (σ) | 0.145275 | 0.0144659 | 0.123724 | 0.144058 | 0.170841 | 0.9999 | 9491 | +| Skew (of log) (γ) | 0.494699 | 0.309876 | -0.0420235 | 0.508394 | 0.981615 | 0.9999 | 9759 | ### Frequency / Quantile Table +While in the **Distribution Results** tab to the left, select Tabular Results to see the frequency plot's value at each return level probability, - - -| AEP (%) | Return Period (yr) | Median | Lower CI | Upper CI | +| Probability | 95.0% CI | 5.0% CI | Posterior Predictive| Posterior Mean | |---|---|---|---|---| -| 50 | 2 | | | | -| 10 | 10 | | | | -| 1 | 100 | | | | -| 0.5 | 200 | | | | -| 0.2 | 500 | | | | +| 1E-06 | 54031.316257562066 | 9165.110307410034 | 46116.62582137766 | 19617.021917559636 | +| 2E-06 | 46721.50839543596 | 8779.767395965824 | 37999.18439573705 | 17965.084607220688 | +| 5E-06 | 38385.61143470683 | 8269.365768389314 | 29698.795720175534 | 15964.011187079663 | +| 1E-05 | 33100.93711300119 | 7872.498753694969 | 24819.409863879744 | 14577.69791315477 | +| 2E-05 | 28433.7841684319 | 7483.270018967832 | 20860.461018886417 | 13292.54052225392 | +| 5E-05 | 23308.201627629398 | 6995.57167680981 | 16716.233177873124 | 11736.641442315871 | +| 0.0001 | 20036.42034911222 | 6626.163991018255 | 14221.25450638549 | 10659.157590427467 | +| 0.0002 | 17188.272175283582 | 6264.134782619214 | 12155.928150363157 | 9660.40921577915 | +| 0.0005 | 13978.206991629932 | 5787.573628833811 | 9945.167803281185 | 8450.963923210415 | +| 0.001 | 11930.629825356993 | 5425.291678366462 | 8583.160724172734 | 7612.740533980664 | +| 0.002 | 10190.960228425516 | 5071.861151707566 | 7433.63755040204 | 6834.701293487262 | +| 0.005 | 8188.712929452412 | 4607.7599330020585 | 6171.932667642047 | 5889.859006677785 | +| 0.01 | 6902.670113275914 | 4248.949920095394 | 5371.716882925127 | 5231.877346858234 | +| 0.02 | 5797.470134115837 | 3882.760729657046 | 4674.052814483974 | 4616.972480559368 | +| 0.05 | 4554.011152929869 | 3383.3208619584093 | 3868.155091079058 | 3860.1791365128565 | +| 0.1 | 3756.6719505125143 | 2986.5413396786366 | 3317.935606324538 | 3320.4337669088036 | +| 0.2 | 3064.777008244417 | 2561.095394666336 | 2792.8827845281053 | 2795.8717674915224 | +| 0.3 | 2692.5667854387993 | 2295.990171541417 | 2485.0020328369114 | 2487.090566368095 | +| 0.5 | 2228.5658447325054 | 1930.7675660324815 | 2073.9297901925297 | 2075.3669093598874 | +| 0.7 | 1882.4383041609392 | 1642.391138926227 | 1757.0141944841844 | 1758.2226064762099 | +| 0.8 | 1715.023252836066 | 1495.654301211657 | 1601.0474527329357 | 1601.7874536498475 | +| 0.9 | 1523.3610690481812 | 1314.3014473936146 | 1420.363783116202 | 1419.8095173319493 | +| 0.95 | 1399.6843891019073 | 1175.8186655724626 | 1295.7336283611808 | 1294.6972551553101 | +| 0.98 | 1290.3527128117498 | 1030.5892726380414 | 1173.407246505538 | 1176.0218461308664 | +| 0.99 | 1234.5580479002801 | 943.2936688860141 | 1096.4923209429799 | 1107.8531207669682 | ### Plots +There are also plenty of plots to explore our results with. Under the **Distribution Results** tab we have a frequency curve. + +![Frequency curve (AEP versus quantile), with the credible band.](../images/bulletin-17c-bayesian-frequency.png) + +*Figure 1: Frequency curve (AEP versus quantile), with the credible band.* + +The **Kernal Density** tab shows an estimate for the pdf of each parameter. + +![Posterior kernel density for mean parameter (µ).](../images/bulletin-17c-bayesian-kernel-density-mean.png) + +*Figure 2: Posterior kernel density for mean parameter (µ).* + +The **Markov Chain Traces** tab explores the traces of each Markov chain as it explores the posterior space in order to converge. -![Frequency curve (AEP versus quantile) for each alternative, with the credible band.](images/bulletin-17c-bayesian-frequency.png) -*Figure: Frequency curve (AEP versus quantile) for each alternative, with the credible band.* +![Markov-chain traces for mean parameter (µ).](../images/bulletin-17c-bayesian-trace-mean.png) -![Posterior kernel density for each parameter.](images/bulletin-17c-bayesian-kernel-density.png) -*Figure: Posterior kernel density for each parameter.* +*Figure 3: Markov-chain traces for mean parameter (µ).* -![Markov-chain traces for each parameter.](images/bulletin-17c-bayesian-trace.png) -*Figure: Markov-chain traces for each parameter.* +Finally, we can investigate the autocorrelation of the chains under the **Autocorrelation** tab. -![Autocorrelation function of the chains, used to estimate effective sample size.](images/bulletin-17c-bayesian-autocorrelation.png) -*Figure: Autocorrelation function of the chains, used to estimate effective sample size.* +![Autocorrelation function of the chains, used to estimate effective sample size, for mean parameter (µ).](../images/bulletin-17c-bayesian-autocorrelation-mean.png) + +*Figure 4: Autocorrelation function of the chains, used to estimate effective sample size, for mean parameter (µ).* ### MCMC Diagnostics -Verify chain convergence before interpreting any results: +One should always verify chain convergence before interpreting any results. There are a variety of ways including: - **R-hat** — should be < 1.01 for every parameter. - **Effective Sample Size (ESS)** — at least a few hundred per parameter. - **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). - **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. -## Next Steps +These can be found under the **Markov Chain Traces** and **MCMC Reports** tabs. -- Compare alternatives via the **Bayesian Model Average** element to combine results from multiple distributions. +## Next Steps +- Compare analyses via the **Bayesian Model Average** element to combine results from multiple distributions. + - Right click the **Univariate Distribution Analysis** drop down and select "New Composite Distribution Analysis" + - Select from the available options in the **Properties** panel to the right - Compute **return-period quantiles** (1%, 0.5%, 0.2% AEP) from the frequency-curve table. - Re-run with informative **quantile priors** if engineering judgment suggests specific upper-bound flood magnitudes. -- Cross-check the LP-III fit against a **Bulletin 17C** fit on the same input data. - -## References - - - ---- - -_This tutorial was generated from the project's `.bestfit` file metadata. The narrative and figure / table sections are placeholders — capture screenshots from the BestFit GUI and paste output tables to complete the guide._ +- Cross-check the LP-III fit against a **Bulletin 17C** fit on the same input data. \ No newline at end of file diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/3-bulletin17C-examples/bulletin17C-examples.bestfit.bak b/examples/4-univariate-distribution-analysis/1-univariate-analysis/3-bulletin17C-examples/bulletin17C-examples.bestfit.bak deleted file mode 100644 index 173a04f..0000000 Binary files a/examples/4-univariate-distribution-analysis/1-univariate-analysis/3-bulletin17C-examples/bulletin17C-examples.bestfit.bak and /dev/null differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/4-measurement-errors/README.txt b/examples/4-univariate-distribution-analysis/1-univariate-analysis/4-measurement-errors/README.txt deleted file mode 100644 index 951532b..0000000 --- a/examples/4-univariate-distribution-analysis/1-univariate-analysis/4-measurement-errors/README.txt +++ /dev/null @@ -1,3 +0,0 @@ -Measurement Errors: - --This example demonstrates how to incorporate measurement errors (or prediction errors) derived from a MOVE.3 analysis. \ No newline at end of file diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/4-measurement-errors/Sinnamahoning-MOVE.3-example.bestfit.bak b/examples/4-univariate-distribution-analysis/1-univariate-analysis/4-measurement-errors/Sinnamahoning-MOVE.3-example.bestfit.bak deleted file mode 100644 index f1a1c1e..0000000 Binary files a/examples/4-univariate-distribution-analysis/1-univariate-analysis/4-measurement-errors/Sinnamahoning-MOVE.3-example.bestfit.bak and /dev/null differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/4-measurement-errors/sinnemahoning-move3-bayesian.bestfit b/examples/4-univariate-distribution-analysis/1-univariate-analysis/4-measurement-errors/sinnemahoning-move3-bayesian.bestfit index 6e8b197..8a2c24b 100644 Binary files a/examples/4-univariate-distribution-analysis/1-univariate-analysis/4-measurement-errors/sinnemahoning-move3-bayesian.bestfit and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/4-measurement-errors/sinnemahoning-move3-bayesian.bestfit differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/4-measurement-errors/sinnemahoning-move3-bayesian.md b/examples/4-univariate-distribution-analysis/1-univariate-analysis/4-measurement-errors/sinnemahoning-move3-bayesian.md index 6a0675c..62665c3 100644 --- a/examples/4-univariate-distribution-analysis/1-univariate-analysis/4-measurement-errors/sinnemahoning-move3-bayesian.md +++ b/examples/4-univariate-distribution-analysis/1-univariate-analysis/4-measurement-errors/sinnemahoning-move3-bayesian.md @@ -31,18 +31,19 @@ Bayesian flood-frequency analysis for Sinnemahoning Creek (USGS gage 01543500) d 3. Open `sinnemahoning-move3-bayesian.bestfit`. ### Exploring the Elements +For each Univariate Distribution anlysis: -For each Univariate Distribution alternative: +1. Click the analysis in the Project Explorer. +2. The **Distirbution Results** tab to the left shoudld automatically open. Navigate to the **Frequency** tab to view the AEP-vs-quantile plot. +3. Open the **Markov Chain Traces** tab on the left to confirm chain mixing (well-mixed traces look like fuzzy caterpillars). +4. Open the **Autocorrelation** tab on the left to check effective sample size. +5. Inspect the **Properties** panel on the right for sampler settings (iterations, warmup, point estimator, credible-interval width). -1. Click the alternative in the Project Explorer. -2. Open the **Frequency** tab to view the AEP-vs-quantile plot. -3. Open the **Markov Chain Trace** tab to confirm chain mixing (well-mixed traces look like fuzzy caterpillars). -4. Open the **Autocorrelation** tab to check effective sample size. -5. Inspect the **Properties** panel for sampler settings (iterations, warmup, point estimator, credible-interval width). +These will be explored more below in the Expected results section. ## Analysis Settings -Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any alternative to inspect: +Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any analysis to inspect: - **Sampler type** (DEMCzs, ARWMH, HMC). - **Iterations / Warm-up Iterations** — total post-warmup samples per chain. @@ -52,66 +53,91 @@ Each Bayesian analysis in this project uses the DEMCzs sampler with project-spec - **Credible Interval Width** — typically 0.90 or 0.95. ## Expected Results +Below are the expected results for Univariate Distribution Analysis labeled "LPIII - No Extension"; this should be the first analysis in the list. +Be sure to explore all of the analyses provided! - +### Parameter -### Parameter Estimates +The parameter estimates are found under the **MCMC Report** tab to the left as parameter summary statistics. - - -| Alternative | Parameter | Mean | Median | Lower CI | Upper CI | R-hat | ESS | +| Parameter | Mean | Std Dev | 5% | Median | 95% |R-hat | ESS | |---|---|---|---|---|---|---|---| -| _(placeholder)_ | | | | | | | | +| Mean (of log) (µ) | 4.12892 | 0.0221622 | 4.09276 | 4.12874 | 4.16581 | 0.9999 | 9547 | +| Std Dev (of log) (σ) | 0.198843 | 0.0177867 | 0.172888 | 0.197371 | 0.230417 | 1.0003 | 9384 | +| Skew (of log) (γ) | 0.41654 | 0.308091 | -0.0942991 | 0.419552 | 0.920473 | 1.0001 | 9262 | -### Frequency / Quantile Table - +### Frequency / Quantile Table +While in the **Distribution Results** tab to the left, select Tabular Results to see the frequency plot's value at each return level probability, -| AEP (%) | Return Period (yr) | Median | Lower CI | Upper CI | +| Probability | 95.0% CI | 5.0% CI | Posterior Predictive| Posterior Mean | |---|---|---|---|---| -| 50 | 2 | | | | -| 10 | 10 | | | | -| 1 | 100 | | | | -| 0.5 | 200 | | | | -| 0.2 | 500 | | | | +| 1E-06 | 941895.394631862 | 93697.05380690159 | 735267.3379703702 | 243612.53274078039 | +| 2E-06 | 779381.079678741 | 88712.06233954296 | 573917.6588298439 | 217996.50974451596 | +| 5E-06 | 604406.8805348062 | 82275.24207965579 | 418260.221232814 | 187736.2031513548 | +| 1E-05 | 498772.12540904374 | 77346.54639604903 | 331969.9443677477 | 167308.4285876564 | +| 2E-05 | 411370.11613768426 | 72679.52437641469 | 265323.3971223406 | 148796.90039229096 | +| 5E-05 | 316030.8276633807 | 66581.13655484354 | 199351.1570918021 | 126981.34093665762 | +| 0.0001 | 258389.40949075267 | 62195.508958255064 | 161799.3893378456 | 112290.22877764553 | +| 0.0002 | 210535.61685370025 | 57732.20230483466 | 132140.01222554533 | 99004.87478072522 | +| 0.0005 | 161058.1285424831 | 52132.54054404573 | 102009.13587884528 | 83384.57556976251 | +| 0.001 | 130653.34196926317 | 47981.16125926004 | 84384.38659480437 | 72888.22365639833 | +| 0.002 | 105817.51922835206 | 43860.27173378878 | 70120.35691466517 | 63410.9785015336 | +| 0.005 | 79806.03681193502 | 38594.861742680354 | 55179.32817845139 | 52280.894544392395 | +| 0.01 | 63941.63232193175 | 34688.79163660984 | 46120.712568126764 | 44801.94250531572 | +| 0.02 | 50752.13456119727 | 30820.354445442663 | 38508.26558266601 | 38037.394600010404 | +| 0.05 | 36928.57393790966 | 25619.23702522122 | 30075.42876025844 | 30046.072956148684 | +| 0.1 | 28628.087872599037 | 21663.4206922105 | 24561.849053410035 | 24601.486246747107 | +| 0.2 | 21823.11134057623 | 17588.170948540053 | 19516.948029978474 | 19543.11907992385 | +| 0.3 | 18374.222692953346 | 15111.841302030358 | 16673.597092675856 | 16686.620244069974 | +| 0.5 | 14247.694600625573 | 11895.375653663723 | 13029.071781658113 | 13036.175880294659 | +| 0.7 | 11312.84821600125 | 9487.161586348799 | 10356.688183756674 | 10363.694127181378 | +| 0.8 | 9927.48413052725 | 8316.149909350368 | 9092.421454693196 | 9095.640884424865 | +| 0.9 | 8413.43431340079 | 6924.188803605242 | 7673.085776103146 | 7666.453647602048 | +| 0.95 | 7458.241617502503 | 5900.295452883388 | 6725.120214136634 | 6714.674314428059 | +| 0.98 | 6651.828039832808 | 4899.74510927318 | 5821.966982130119 | 5836.695473679198 | +| 0.99 | 6242.04360422965 | 4305.4392581579505 | 5272.358675896718 | 5343.845238727602 | ### Plots +There are also plenty of plots to explore our results with. Under the **Distribution Results** tab we have a frequency curve. + +![Frequency curve (AEP versus quantile), with the credible band.](../images/sinnemahoning-bayesian-frequency.png) + +*Figure 1: Frequency curve (AEP versus quantile), with the credible band.* + +The **Kernal Density** tab shows an estimate for the pdf of each parameter. + +![Posterior kernel density for mean parameter (µ).](../images/sinnemahoning-bayesian-kernel-density-mean.png) + +*Figure 2: Posterior kernel density for mean parameter (µ).* + +The **Markov Chain Traces** tab explores the traces of each Markov chain as it explores the posterior space in order to converge. -![Frequency curve (AEP versus quantile) for each alternative, with the credible band.](images/sinnemahoning-bayesian-frequency.png) -*Figure: Frequency curve (AEP versus quantile) for each alternative, with the credible band.* +![Markov-chain traces for mean parameter (µ).](../images/sinnemahoning-bayesian-trace-mean.png) -![Posterior kernel density for each parameter.](images/sinnemahoning-bayesian-kernel-density.png) -*Figure: Posterior kernel density for each parameter.* +*Figure 3: Markov-chain traces for mean parameter (µ).* -![Markov-chain traces for each parameter.](images/sinnemahoning-bayesian-trace.png) -*Figure: Markov-chain traces for each parameter.* +Finally, we can investigate the autocorrelation of the chains under the **Autocorrelation** tab. -![Autocorrelation function of the chains, used to estimate effective sample size.](images/sinnemahoning-bayesian-autocorrelation.png) -*Figure: Autocorrelation function of the chains, used to estimate effective sample size.* +![Autocorrelation function of the chains, used to estimate effective sample size, for mean parameter (µ).](../images/sinnemahoning-bayesian-autocorrelation-mean.png) + +*Figure 4: Autocorrelation function of the chains, used to estimate effective sample size, for mean parameter (µ).* ### MCMC Diagnostics -Verify chain convergence before interpreting any results: +One should always verify chain convergence before interpreting any results. There are a variety of ways including: - **R-hat** — should be < 1.01 for every parameter. - **Effective Sample Size (ESS)** — at least a few hundred per parameter. - **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). - **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. -## Next Steps +These can be found under the **Markov Chain Traces** and **MCMC Reports** tabs. -- Compare alternatives via the **Bayesian Model Average** element to combine results from multiple distributions. +## Next Steps +- Compare analyses via the **Bayesian Model Average** element to combine results from multiple distributions. + - Right click the **Univariate Distribution Analysis** drop down and select "New Composite Distribution Analysis" + - Select from the available options in the **Properties** panel to the right - Compute **return-period quantiles** (1%, 0.5%, 0.2% AEP) from the frequency-curve table. - Re-run with informative **quantile priors** if engineering judgment suggests specific upper-bound flood magnitudes. -- Cross-check the LP-III fit against a **Bulletin 17C** fit on the same input data. - -## References - - - ---- - -_This tutorial was generated from the project's `.bestfit` file metadata. The narrative and figure / table sections are placeholders — capture screenshots from the BestFit GUI and paste output tables to complete the guide._ +- Cross-check the LP-III fit against a **Bulletin 17C** fit on the same input data. \ No newline at end of file diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/5-nonstationary-ffa/nsffa-brays-bayou-texas.bestfit b/examples/4-univariate-distribution-analysis/1-univariate-analysis/5-nonstationary-ffa/nsffa-brays-bayou-texas.bestfit index 24c6b71..7cf355f 100644 Binary files a/examples/4-univariate-distribution-analysis/1-univariate-analysis/5-nonstationary-ffa/nsffa-brays-bayou-texas.bestfit and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/5-nonstationary-ffa/nsffa-brays-bayou-texas.bestfit differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/5-nonstationary-ffa/nsffa-brays-bayou-texas.md b/examples/4-univariate-distribution-analysis/1-univariate-analysis/5-nonstationary-ffa/nsffa-brays-bayou-texas.md index 7ba4969..151ddca 100644 --- a/examples/4-univariate-distribution-analysis/1-univariate-analysis/5-nonstationary-ffa/nsffa-brays-bayou-texas.md +++ b/examples/4-univariate-distribution-analysis/1-univariate-analysis/5-nonstationary-ffa/nsffa-brays-bayou-texas.md @@ -40,17 +40,16 @@ Nonstationary flood-frequency analysis (NSFFA) for Brays Bayou (USGS gage 080750 3. Open `nsffa-brays-bayou-texas.bestfit`. ### Exploring the Elements +For each Univariate Distribution anlysis: -For each NSFFA alternative: - -1. Click the alternative in the Project Explorer. -2. Open the **Frequency** tab. The displayed curve is conditional on the time index in the **Properties** panel — change it to see how the curve evolves. +1. Click the analysis in the Project Explorer. +2. The **Distirbution Results** tab to the left shoudld automatically open. Navigate to the **Frequency** tab. The displayed curve is conditional on the time index in the **Properties** panel — change it to see how the curve evolves. 3. Open the **Chronology** tab to view the time-varying location / scale through the record. 4. Use the **Bayesian Model Average** Composite Distribution element to view the trend-marginalized AEP curve. ## Analysis Settings -Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any alternative to inspect: +Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any analysis to inspect: - **Sampler type** (DEMCzs, ARWMH, HMC). - **Iterations / Warm-up Iterations** — total post-warmup samples per chain. @@ -60,65 +59,87 @@ Each Bayesian analysis in this project uses the DEMCzs sampler with project-spec - **Credible Interval Width** — typically 0.90 or 0.95. ## Expected Results - - +Below are the expected results for Univariate Distribution Analysis labeled "NSFFA - Constant"; this should be the first analysis in the list. +Be sure to explore all of the analyses provided! ### Parameter Estimates +The parameter estimates are found under the **MCMC Report** tab to the left as parameter summary statistics. - - -| Alternative | Parameter | Mean | Median | Lower CI | Upper CI | R-hat | ESS | +| Parameter | Mean | Std Dev | 5% | Median | 95% |R-hat | ESS | |---|---|---|---|---|---|---|---| -| _(placeholder)_ | | | | | | | | +| Mean (of log) (µ) (α) | 2.45714 | 0.0417119 | 2.38506 | 2.45938 | 2.52123 | 1.0003 | 9789 | +| Std Dev (of log) (σ) (α) | 0.387815 | 0.0406779 | 0.328395 | 0.383662 | 0.460926 | 1.0002 | 8966 | +| Skew (of log) (γ) (α) | -1.28685 | 0.182 | -1.55975 | -1.29898 | -0.971748 | 0.9998 | 9146 | -### Frequency / Quantile Table - +### Frequency / Quantile Table +While in the **Distribution Results** tab to the left, select Tabular Results to see the frequency plot's value at each return level probability, -| AEP (%) | Return Period (yr) | Median | Lower CI | Upper CI | +| Probability | 95.0% CI | 5.0% CI | Posterior Predictive| Posterior Mean | |---|---|---|---|---| -| 50 | 2 | | | | -| 10 | 10 | | | | -| 1 | 100 | | | | -| 0.5 | 200 | | | | -| 0.2 | 500 | | | | +| 1E-06 | 1535.6750409383017 | 1011.3231604415923 | 2440.947062471401 | 1144.3953911425606 | +| 2E-06 | 1526.439921163896 | 1011.079221717383 | 2218.040197672377 | 1143.2570810365887 | +| 5E-06 | 1511.4053083298231 | 1010.4816080990164 | 1968.8288912874468 | 1141.151954429344 | +| 1E-05 | 1497.73854393094 | 1009.7284511172976 | 1811.6787182064893 | 1138.9354898325948 | +| 2E-05 | 1480.3540408128738 | 1008.9045196093269 | 1677.3451624765587 | 1135.9821998684095 | +| 5E-05 | 1455.9624769722536 | 1006.7266330158031 | 1526.309801049989 | 1130.5202963793236 | +| 0.0001 | 1433.776267121642 | 1004.5605228995514 | 1428.0407632781198 | 1124.7691496081466 | +| 0.0002 | 1403.7469000769092 | 1001.6825865359498 | 1340.4357817893417 | 1117.10552273515 | +| 0.0005 | 1357.5733267806688 | 994.8291177658533 | 1239.0712280329808 | 1102.9302385350177 | +| 0.001 | 1314.874114346102 | 986.6121658938863 | 1172.7881013391584 | 1088.001357538545 | +| 0.002 | 1266.3892117339851 | 973.426289748229 | 1113.576609949211 | 1068.1029401725586 | +| 0.005 | 1190.5927019894484 | 945.032146556927 | 1043.396857466372 | 1031.2797199485976 | +| 0.01 | 1122.4461270470747 | 912.5069113102742 | 993.9666579292534 | 992.4701399073111 | +| 0.02 | 1043.0371108015129 | 865.816274127052 | 940.3909776201293 | 940.6855709693796 | +| 0.05 | 921.5118924019764 | 773.2886054946199 | 845.0843270080293 | 844.6318418131355 | +| 0.1 | 813.5626684689445 | 673.5684248316068 | 744.1517180677334 | 742.9503885233227 | +| 0.2 | 673.384299209667 | 542.7642399538721 | 607.4692730268941 | 606.1456459369981 | +| 0.3 | 568.3695908425519 | 446.4669942344964 | 505.59004692251887 | 504.427413237681 | +| 0.5 | 398.78006110194895 | 296.56343867929337 | 346.0681286904276 | 345.11691735411614 | +| 0.7 | 255.86812537244407 | 174.22598352451647 | 213.6729766403919 | 212.8479705344418 | +| 0.8 | 187.99954780107595 | 117.38013550359746 | 151.09871611509578 | 150.5027531405478 | +| 0.9 | 117.27357905965948 | 60.8193904095075 | 86.67911029592749 | 86.64544936715555 | +| 0.95 | 76.19661824735317 | 32.04391250293293 | 50.94992563768222 | 51.4557686382786 | +| 0.98 | 44.674889821465655 | 13.92604975981927 | 25.665899186517873 | 26.609078077867363 | +| 0.99 | 30.568587417174797 | 7.530532660844613 | 15.34745692572472 | 16.404741950947624 | ### Plots +There are also plenty of plots to explore our results with. Under the **Distribution Results** tab we have a frequency curve. + +![Frequency curve (AEP versus quantile), with the credible band.](../images/nsffa-brays-bayou-frequency.png) + +*Figure 1: Frequency curve (AEP versus quantile), with the credible band.* + +The **Kernal Density** tab shows an estimate for the pdf of each parameter. + +![Posterior kernel density for mean parameter (µ).](../images/nsffa-brays-bayou-kernel-density-mean.png) + +*Figure 2: Posterior kernel density for mean parameter (µ).* -![Frequency curve (AEP versus quantile) for each alternative, with the credible band.](images/nsffa-brays-bayou-frequency.png) -*Figure: Frequency curve (AEP versus quantile) for each alternative, with the credible band.* +The **Markov Chain Traces** tab explores the traces of each Markov chain as it explores the posterior space in order to converge. -![Posterior kernel density for each parameter.](images/nsffa-brays-bayou-kernel-density.png) -*Figure: Posterior kernel density for each parameter.* +![Markov-chain traces for mean parameter (µ).](../images/nsffa-brays-bayou-trace-mean.png) -![Markov-chain traces for each parameter.](images/nsffa-brays-bayou-trace.png) -*Figure: Markov-chain traces for each parameter.* +*Figure 3: Markov-chain traces for mean parameter (µ).* -![Autocorrelation function of the chains, used to estimate effective sample size.](images/nsffa-brays-bayou-autocorrelation.png) -*Figure: Autocorrelation function of the chains, used to estimate effective sample size.* +Finally, we can investigate the autocorrelation of the chains under the **Autocorrelation** tab. + +![Autocorrelation function of the chains, used to estimate effective sample size,for mean parameter (µ).](../images/nsffa-brays-bayou-autocorrelation-mean.png) + +*Figure 4: Autocorrelation function of the chains, used to estimate effective sample size,for mean parameter (µ).* ### MCMC Diagnostics -Verify chain convergence before interpreting any results: +One should always verify chain convergence before interpreting any results. There are a variety of ways including: - **R-hat** — should be < 1.01 for every parameter. - **Effective Sample Size (ESS)** — at least a few hundred per parameter. - **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). - **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. -## Next Steps +These can be found under the **Markov Chain Traces** and **MCMC Reports** tabs. -- Compare alternatives by **DIC**, **WAIC**, and **LOO-CV** information criteria. -- Average results across alternatives via the **Bayesian Model Average** Composite Distribution element. +## Next Steps +- Compare analyses by **DIC**, **WAIC**, and **LOO-CV** information criteria. +- Average results across analyses via the **Bayesian Model Average** Composite Distribution element. - Project **conditional return-period quantiles** for future time indices using the trend functions. - -## References - - - ---- - -_This tutorial was generated from the project's `.bestfit` file metadata. The narrative and figure / table sections are placeholders — capture screenshots from the BestFit GUI and paste output tables to complete the guide._ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/5-nonstationary-ffa/nsffa-oc-fisher-dam.bestfit b/examples/4-univariate-distribution-analysis/1-univariate-analysis/5-nonstationary-ffa/nsffa-oc-fisher-dam.bestfit index 7e6afd5..6375f64 100644 Binary files a/examples/4-univariate-distribution-analysis/1-univariate-analysis/5-nonstationary-ffa/nsffa-oc-fisher-dam.bestfit and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/5-nonstationary-ffa/nsffa-oc-fisher-dam.bestfit differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/5-nonstationary-ffa/nsffa-oc-fisher-dam.md b/examples/4-univariate-distribution-analysis/1-univariate-analysis/5-nonstationary-ffa/nsffa-oc-fisher-dam.md index 6afb854..df9b0f0 100644 --- a/examples/4-univariate-distribution-analysis/1-univariate-analysis/5-nonstationary-ffa/nsffa-oc-fisher-dam.md +++ b/examples/4-univariate-distribution-analysis/1-univariate-analysis/5-nonstationary-ffa/nsffa-oc-fisher-dam.md @@ -37,17 +37,16 @@ Nonstationary flood-frequency analysis (NSFFA) for inflows to OC Fisher Dam, Tex 3. Open `nsffa-oc-fisher-dam.bestfit`. ### Exploring the Elements +For each Univariate Distribution anlysis: -For each NSFFA alternative: - -1. Click the alternative in the Project Explorer. -2. Open the **Frequency** tab. The displayed curve is conditional on the time index in the **Properties** panel — change it to see how the curve evolves. +1. Click the analysis in the Project Explorer. +2. The **Distirbution Results** tab to the left shoudld automatically open. Navigate to the **Frequency** tab. The displayed curve is conditional on the time index in the **Properties** panel — change it to see how the curve evolves. 3. Open the **Chronology** tab to view the time-varying location / scale through the record. 4. Use the **Bayesian Model Average** Composite Distribution element to view the trend-marginalized AEP curve. - + ## Analysis Settings -Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any alternative to inspect: +Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any analysis to inspect: - **Sampler type** (DEMCzs, ARWMH, HMC). - **Iterations / Warm-up Iterations** — total post-warmup samples per chain. @@ -57,65 +56,85 @@ Each Bayesian analysis in this project uses the DEMCzs sampler with project-spec - **Credible Interval Width** — typically 0.90 or 0.95. ## Expected Results - - +Below are the expected results for Univariate Distribution Analysis labeled "SFFA"; this should be the first analysis in the list. +Be sure to explore all of the analyses provided! ### Parameter Estimates +The parameter estimates are found under the **MCMC Report** tab to the left as parameter summary statistics. - - -| Alternative | Parameter | Mean | Median | Lower CI | Upper CI | R-hat | ESS | +| Parameter | Mean | Std Dev | 5% | Median | 95% |R-hat | ESS | |---|---|---|---|---|---|---|---| -| _(placeholder)_ | | | | | | | | +| Mean (of log) (µ) | 1.30722 | 0.0653592 | 1.20199 | 1.30708 | 1.41529 | 0.9998 | 9173 | +| Std Dev (of log) (σ) | 0.710358 | 0.0451466 | 0.641823 | 0.707455 | 0.788422 | 0.9999 | 9044 | +| Skew (of log) (γ) | 0.0292537 | 0.196149 | -0.303485 | 0.0354567 | 0.343264 | 0.9999 | 9686 | ### Frequency / Quantile Table +While in the **Distribution Results** tab to the left, select Tabular Results to see the frequency plot's value at each return level probability, - - -| AEP (%) | Return Period (yr) | Median | Lower CI | Upper CI | +| Probability | 95.0% CI | 5.0% CI | Posterior Predictive| Posterior Mean | |---|---|---|---|---| -| 50 | 2 | | | | -| 10 | 10 | | | | -| 1 | 100 | | | | -| 0.5 | 200 | | | | -| 0.2 | 500 | | | | +| 1E-06 | 302046.8803614846 | 11247.799806657618 | 130545.69418424394 | 57405.18099912636 | +| 2E-06 | 214050.29079938665 | 9744.457929884586 | 91689.25194575514 | 45020.32594576404 | +| 5E-06 | 133093.4494137589 | 8037.138869476555 | 57528.890995286885 | 32309.784195425098 | +| 1E-05 | 92275.36551455075 | 6846.878985724154 | 40441.78593705815 | 24920.01663013401 | +| 2E-05 | 63455.7595075625 | 5756.474127766755 | 28418.02754282829 | 19060.56054273523 | +| 5E-05 | 38368.1233392033 | 4498.58322699299 | 17792.84356584133 | 13183.254938483899 | +| 0.0001 | 25959.82839264131 | 3703.7632737824065 | 12454.9484864471 | 9853.593903038738 | +| 0.0002 | 17370.707110738 | 3009.79305453177 | 8688.739188699017 | 7277.219343602523 | +| 0.0005 | 10100.999216362416 | 2223.4395070993623 | 5355.803251038273 | 4772.627452835385 | +| 0.001 | 6622.266600951803 | 1735.5899675790176 | 3682.268564069477 | 3404.3225043920447 | +| 0.002 | 4264.814937152258 | 1324.5807503606418 | 2504.815504430233 | 2382.2285796151045 | +| 0.005 | 2320.30868995125 | 885.4800792787247 | 1470.0596054214902 | 1433.8008763510543 | +| 0.01 | 1423.4128332037897 | 623.7909401110849 | 957.385423015678 | 944.1051925998491 | +| 0.02 | 850.688679860863 | 418.2615573889831 | 603.7862131288001 | 598.7336802551114 | +| 0.05 | 412.27046090070553 | 222.62127720905525 | 305.0004330169159 | 303.0596269617336 | +| 0.1 | 221.72664475180224 | 124.84198204300263 | 166.92862842434786 | 165.87164656242902 | +| 0.2 | 106.90801984518048 | 60.64808714622956 | 80.61161823482772 | 80.17439343419109 | +| 0.3 | 63.321943588692626 | 36.10123720421038 | 47.74147209995996 | 47.555637149608884 | +| 0.5 | 26.59748677598419 | 15.390452803634735 | 20.14723890916291 | 20.12575850397788 | +| 0.7 | 11.316810525793144 | 6.511585897438564 | 8.55450328156172 | 8.554750725731763 | +| 0.8 | 6.83744051412828 | 3.7935027160091006 | 5.110933724740746 | 5.10946327432983 | +| 0.9 | 3.5226856616438345 | 1.717434490162799 | 2.5055993732941477 | 2.50673698759172 | +| 0.95 | 2.1057335913970343 | 0.8589285604107446 | 1.3857106828817778 | 1.395459254330488 | +| 0.98 | 1.2181058964432496 | 0.37710741463945474 | 0.701233486818966 | 0.7235809412629356 | +| 0.99 | 0.8657450107280343 | 0.21521422228204037 | 0.4379718320865267 | 0.4677038455215546 | ### Plots +There are also plenty of plots to explore our results with. Under the **Distribution Results** tab we have a frequency curve. -![Frequency curve (AEP versus quantile) for each alternative, with the credible band.](images/nsffa-oc-fisher-frequency.png) -*Figure: Frequency curve (AEP versus quantile) for each alternative, with the credible band.* +![Frequency curve (AEP versus quantile), with the credible band.](../images/nsffa-oc-fisher-frequency.png) -![Posterior kernel density for each parameter.](images/nsffa-oc-fisher-kernel-density.png) -*Figure: Posterior kernel density for each parameter.* +*Figure 1 Frequency curve (AEP versus quantile), with the credible band.* -![Markov-chain traces for each parameter.](images/nsffa-oc-fisher-trace.png) -*Figure: Markov-chain traces for each parameter.* +The **Kernal Density** tab shows an estimate for the pdf of each parameter. -![Autocorrelation function of the chains, used to estimate effective sample size.](images/nsffa-oc-fisher-autocorrelation.png) -*Figure: Autocorrelation function of the chains, used to estimate effective sample size.* +![Posterior kernel density for mean parameter (µ).](../images/nsffa-oc-fisher-kernel-density-mean.png) -### MCMC Diagnostics +*Figure 2: Posterior kernel density for mean parameter (µ).* -Verify chain convergence before interpreting any results: +The **Markov Chain Traces** tab explores the traces of each Markov chain as it explores the posterior space in order to converge. -- **R-hat** — should be < 1.01 for every parameter. -- **Effective Sample Size (ESS)** — at least a few hundred per parameter. -- **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). -- **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. +![Markov-chain traces for mean parameter (µ).](../images/nsffa-oc-fisher-trace-mean.png) -## Next Steps +*Figure 3: Markov-chain traces for mean parameter (µ).* -- Compare alternatives by **DIC**, **WAIC**, and **LOO-CV** information criteria. -- Average results across alternatives via the **Bayesian Model Average** Composite Distribution element. -- Project **conditional return-period quantiles** for future time indices using the trend functions. +Finally, we can investigate the autocorrelation of the chains under the **Autocorrelation** tab. -## References +![Autocorrelation function of the chains, used to estimate effective sample size, for mean parameter (µ).](../images/nsffa-oc-fisher-autocorrelation-mean.png) - +### MCMC Diagnostics +One should always verify chain convergence before interpreting any results. There are a variety of ways including: + +- **R-hat** — should be < 1.01 for every parameter. +- **Effective Sample Size (ESS)** — at least a few hundred per parameter. +- **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). +- **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. ---- +These can be found under the **Markov Chain Traces** and **MCMC Reports** tabs. -_This tutorial was generated from the project's `.bestfit` file metadata. The narrative and figure / table sections are placeholders — capture screenshots from the BestFit GUI and paste output tables to complete the guide._ +## Next Steps +- Compare analyses by **DIC**, **WAIC**, and **LOO-CV** information criteria. +- Average results across analyses via the **Bayesian Model Average** Composite Distribution element. +- Project **conditional return-period quantiles** for future time indices using the trend functions. diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/5-nonstationary-ffa/nsffa-synthetic-data.bestfit b/examples/4-univariate-distribution-analysis/1-univariate-analysis/5-nonstationary-ffa/nsffa-synthetic-data.bestfit index d743ee0..606f206 100644 Binary files a/examples/4-univariate-distribution-analysis/1-univariate-analysis/5-nonstationary-ffa/nsffa-synthetic-data.bestfit and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/5-nonstationary-ffa/nsffa-synthetic-data.bestfit differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/5-nonstationary-ffa/nsffa-synthetic-data.md b/examples/4-univariate-distribution-analysis/1-univariate-analysis/5-nonstationary-ffa/nsffa-synthetic-data.md index 385b8ef..08bcfbd 100644 --- a/examples/4-univariate-distribution-analysis/1-univariate-analysis/5-nonstationary-ffa/nsffa-synthetic-data.md +++ b/examples/4-univariate-distribution-analysis/1-univariate-analysis/5-nonstationary-ffa/nsffa-synthetic-data.md @@ -43,17 +43,16 @@ Synthetic NSFFA datasets covering nine trend types (constant, cubic, exponential 3. Open `nsffa-synthetic-data.bestfit`. ### Exploring the Elements +For each Univariate Distribution anlysis: -For each NSFFA alternative: - -1. Click the alternative in the Project Explorer. -2. Open the **Frequency** tab. The displayed curve is conditional on the time index in the **Properties** panel — change it to see how the curve evolves. +1. Click the analysis in the Project Explorer. +2. The **Distirbution Results** tab to the left shoudld automatically open. Navigate to the **Frequency** tab. The displayed curve is conditional on the time index in the **Properties** panel — change it to see how the curve evolves. 3. Open the **Chronology** tab to view the time-varying location / scale through the record. 4. Use the **Bayesian Model Average** Composite Distribution element to view the trend-marginalized AEP curve. ## Analysis Settings -Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any alternative to inspect: +Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any analysis to inspect: - **Sampler type** (DEMCzs, ARWMH, HMC). - **Iterations / Warm-up Iterations** — total post-warmup samples per chain. @@ -63,65 +62,87 @@ Each Bayesian analysis in this project uses the DEMCzs sampler with project-spec - **Credible Interval Width** — typically 0.90 or 0.95. ## Expected Results - - +Below are the expected results for Univariate Distribution Analysis labeled "NSFFA - Constant Trend"; this should be the first analysis in the list. +Be sure to explore all of the analyses provided! ### Parameter Estimates +The parameter estimates are found under the **MCMC Report** tab to the left as parameter summary statistics. - - -| Alternative | Parameter | Mean | Median | Lower CI | Upper CI | R-hat | ESS | +| Parameter | Mean | Std Dev | 5% | Median | 95% |R-hat | ESS | |---|---|---|---|---|---|---|---| -| _(placeholder)_ | | | | | | | | +| Mean (µ) (α) | 99.5411 | 1.57796 | 97.0008 | 99.5288 | 102.129 | 0.9998 | 9148 | +| Std Dev (σ) (α) | 15.8357 | 1.13377 | 14.0828 | 15.7845 | 17.805 | 0.9998 | 9502 | ### Frequency / Quantile Table +While in the **Distribution Results** tab to the left, select Tabular Results to see the frequency plot's value at each return level probability, - - -| AEP (%) | Return Period (yr) | Median | Lower CI | Upper CI | +| Probability | 95.0% CI | 5.0% CI | Posterior Predictive| Posterior Mean | |---|---|---|---|---| -| 50 | 2 | | | | -| 10 | 10 | | | | -| 1 | 100 | | | | -| 0.5 | 200 | | | | -| 0.2 | 500 | | | | +| 1E-06 | 184.3986811306106 | 166.09160370885257 | 179.33533268307318 | 174.81488380694753 | +| 2E-06 | 181.88080292982076 | 164.08918745976325 | 176.67763039698977 | 172.56554944105454 | +| 5E-06 | 178.44582262855764 | 161.31244993389606 | 173.08662954494156 | 169.49011381427005 | +| 1E-05 | 175.75424923029334 | 159.1469807991118 | 170.30410710057805 | 167.0786111709531 | +| 2E-05 | 173.00438342411556 | 156.91484360629414 | 167.45756643293393 | 164.58589480096975 | +| 5E-05 | 169.14392802962823 | 153.84694126315034 | 163.58167869595133 | 161.15132408095576 | +| 0.0001 | 166.11598067273457 | 151.40596229309372 | 160.5503627912524 | 158.43430664208742 | +| 0.0002 | 162.93926571455387 | 148.8749121767023 | 157.4210416299446 | 155.60078140355856 | +| 0.0005 | 158.54315230335658 | 145.34262025093224 | 153.1062034254563 | 151.64886929267988 | +| 0.001 | 155.0204741418768 | 142.4920320734264 | 149.6808122127199 | 148.47706585537478 | +| 0.002 | 151.27759829038555 | 139.46741034431665 | 146.0892696102765 | 145.1187789110287 | +| 0.005 | 145.980630113438 | 135.1639741876048 | 141.0245624714157 | 140.33113164264498 | +| 0.01 | 141.60790311061032 | 131.59322710581668 | 136.8899450490493 | 136.38041731608803 | +| 0.02 | 136.8604898357548 | 127.6689386205512 | 132.4127272347358 | 132.06362054180232 | +| 0.05 | 129.77236484978837 | 121.76240421762942 | 125.76625179360431 | 125.58847544389704 | +| 0.1 | 123.50434331143296 | 116.45857822114345 | 119.91810394534339 | 119.83533116499021 | +| 0.2 | 116.0014118466962 | 109.92979217138674 | 112.89030351568675 | 112.86872419694997 | +| 0.3 | 110.66639394648573 | 105.16344498655792 | 107.8486229350258 | 107.84531043395849 | +| 0.5 | 102.12866281849715 | 97.00083250682037 | 99.5392154882996 | 99.54105860048675 | +| 0.7 | 93.9480914020765 | 88.45153227188185 | 91.23085573275128 | 91.23680676701501 | +| 0.8 | 89.17261482814797 | 83.13769648779389 | 86.19093384076564 | 86.21339300402353 | +| 0.9 | 82.61900231978896 | 75.6086621579995 | 79.16663086368398 | 79.24678603598329 | +| 0.95 | 77.30162024358943 | 69.3085800266881 | 73.32217762282431 | 73.49364175707646 | +| 0.98 | 71.36971153508752 | 62.20214921843593 | 66.68084525691921 | 67.01849665917116 | +| 0.99 | 67.44003985262658 | 57.443486957319735 | 62.207857879084564 | 62.70169988488546 | ### Plots +There are also plenty of plots to explore our results with. Under the **Distribution Results** tab we have a frequency curve. -![Frequency curve (AEP versus quantile) for each alternative, with the credible band.](images/nsffa-synthetic-frequency.png) -*Figure: Frequency curve (AEP versus quantile) for each alternative, with the credible band.* +![Frequency curve (AEP versus quantile), with the credible band.](../images/nsffa-synthetic-frequency.png) -![Posterior kernel density for each parameter.](images/nsffa-synthetic-kernel-density.png) -*Figure: Posterior kernel density for each parameter.* +*Figure 1: Frequency curve (AEP versus quantile), with the credible band.* -![Markov-chain traces for each parameter.](images/nsffa-synthetic-trace.png) -*Figure: Markov-chain traces for each parameter.* +The **Kernal Density** tab shows an estimate for the pdf of each parameter. -![Autocorrelation function of the chains, used to estimate effective sample size.](images/nsffa-synthetic-autocorrelation.png) -*Figure: Autocorrelation function of the chains, used to estimate effective sample size.* +![Posterior kernel density for mean parameter (µ).](../images/nsffa-synthetic-kernel-density-mean.png) -### MCMC Diagnostics +*Figure 2: Posterior kernel density for mean parameter (µ).* -Verify chain convergence before interpreting any results: +The **Markov Chain Traces** tab explores the traces of each Markov chain as it explores the posterior space in order to converge. -- **R-hat** — should be < 1.01 for every parameter. -- **Effective Sample Size (ESS)** — at least a few hundred per parameter. -- **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). -- **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. +![Markov-chain traces for mean parameter (µ).](../images/nsffa-synthetic-trace-mean.png) -## Next Steps +*Figure 3: Markov-chain traces for mean parameter (µ).* + +Finally, we can investigate the autocorrelation of the chains under the **Autocorrelation** tab. -- Compare alternatives by **DIC**, **WAIC**, and **LOO-CV** information criteria. -- Average results across alternatives via the **Bayesian Model Average** Composite Distribution element. -- Project **conditional return-period quantiles** for future time indices using the trend functions. +![Autocorrelation function of the chains, used to estimate effective sample size, for mean parameter (µ).](../images/nsffa-synthetic-autocorrelation-mean.png) -## References +*Figure 4: Autocorrelation function of the chains, used to estimate effective sample size, for mean parameter (µ).* - +These can be found under the **Markov Chain Traces** and **MCMC Reports** tabs ---- +## Next Steps -_This tutorial was generated from the project's `.bestfit` file metadata. The narrative and figure / table sections are placeholders — capture screenshots from the BestFit GUI and paste output tables to complete the guide._ +- Compare analyses via the **Bayesian Model Average** element to combine results from multiple distributions. + - Right click the **Univariate Distribution Analysis** drop down and select "New Composite Distribution Analysis" + - Select from the available options in the **Properties** panel to the right +- Compare analyses by **DIC**, **WAIC**, and **LOO-CV** information criteria. +- Project **conditional return-period quantiles** for future time indices using the trend functions. \ No newline at end of file diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/arr-flike-examples-autocorrelation-mean.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/arr-flike-examples-autocorrelation-mean.png new file mode 100644 index 0000000..7e6d46b Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/arr-flike-examples-autocorrelation-mean.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/arr-flike-examples-frequency.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/arr-flike-examples-frequency.png new file mode 100644 index 0000000..fd72b9a Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/arr-flike-examples-frequency.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/arr-flike-examples-kernel-density-mean.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/arr-flike-examples-kernel-density-mean.png new file mode 100644 index 0000000..84d6e37 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/arr-flike-examples-kernel-density-mean.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/arr-flike-examples-trace-mean.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/arr-flike-examples-trace-mean.png new file mode 100644 index 0000000..ebaabb9 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/arr-flike-examples-trace-mean.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/bulletin-17c-bayesian-autocorrelation-mean.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/bulletin-17c-bayesian-autocorrelation-mean.png new file mode 100644 index 0000000..7345469 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/bulletin-17c-bayesian-autocorrelation-mean.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/bulletin-17c-bayesian-frequency.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/bulletin-17c-bayesian-frequency.png new file mode 100644 index 0000000..b4bc953 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/bulletin-17c-bayesian-frequency.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/bulletin-17c-bayesian-kernel-density-mean.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/bulletin-17c-bayesian-kernel-density-mean.png new file mode 100644 index 0000000..0ada19c Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/bulletin-17c-bayesian-kernel-density-mean.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/bulletin-17c-bayesian-trace-mean.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/bulletin-17c-bayesian-trace-mean.png new file mode 100644 index 0000000..5611ad0 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/bulletin-17c-bayesian-trace-mean.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-brays-bayou-autocorrelation-mean.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-brays-bayou-autocorrelation-mean.png new file mode 100644 index 0000000..406b89c Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-brays-bayou-autocorrelation-mean.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-brays-bayou-frequency.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-brays-bayou-frequency.png new file mode 100644 index 0000000..86c8bdf Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-brays-bayou-frequency.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-brays-bayou-kernel-density-mean.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-brays-bayou-kernel-density-mean.png new file mode 100644 index 0000000..6a973da Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-brays-bayou-kernel-density-mean.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-brays-bayou-trace-mean.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-brays-bayou-trace-mean.png new file mode 100644 index 0000000..6108321 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-brays-bayou-trace-mean.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-oc-fisher-autocorrelation-mean.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-oc-fisher-autocorrelation-mean.png new file mode 100644 index 0000000..5a27605 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-oc-fisher-autocorrelation-mean.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-oc-fisher-frequency.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-oc-fisher-frequency.png new file mode 100644 index 0000000..b5f356f Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-oc-fisher-frequency.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-oc-fisher-kernel-density-mean.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-oc-fisher-kernel-density-mean.png new file mode 100644 index 0000000..59bce27 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-oc-fisher-kernel-density-mean.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-oc-fisher-trace-mean.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-oc-fisher-trace-mean.png new file mode 100644 index 0000000..fe344a2 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-oc-fisher-trace-mean.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-synthetic-autocorrelation-mean.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-synthetic-autocorrelation-mean.png new file mode 100644 index 0000000..eab19b8 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-synthetic-autocorrelation-mean.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-synthetic-frequency.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-synthetic-frequency.png new file mode 100644 index 0000000..a795e9f Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-synthetic-frequency.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-synthetic-kernel-density-mean.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-synthetic-kernel-density-mean.png new file mode 100644 index 0000000..16517c9 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-synthetic-kernel-density-mean.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-synthetic-trace-mean.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-synthetic-trace-mean.png new file mode 100644 index 0000000..e20956b Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/nsffa-synthetic-trace-mean.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/sinnemahoning-bayesian-autocorrelation-mean.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/sinnemahoning-bayesian-autocorrelation-mean.png new file mode 100644 index 0000000..622db56 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/sinnemahoning-bayesian-autocorrelation-mean.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/sinnemahoning-bayesian-frequency.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/sinnemahoning-bayesian-frequency.png new file mode 100644 index 0000000..1dbfe87 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/sinnemahoning-bayesian-frequency.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/sinnemahoning-bayesian-kernel-density-mean.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/sinnemahoning-bayesian-kernel-density-mean.png new file mode 100644 index 0000000..cd1e6ec Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/sinnemahoning-bayesian-kernel-density-mean.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/sinnemahoning-bayesian-trace-mean.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/sinnemahoning-bayesian-trace-mean.png new file mode 100644 index 0000000..3db89b9 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/sinnemahoning-bayesian-trace-mean.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/viglione-et-al-2013-autocorrelation-location.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/viglione-et-al-2013-autocorrelation-location.png new file mode 100644 index 0000000..08c6133 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/viglione-et-al-2013-autocorrelation-location.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/viglione-et-al-2013-frequency.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/viglione-et-al-2013-frequency.png new file mode 100644 index 0000000..31e5c48 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/viglione-et-al-2013-frequency.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/viglione-et-al-2013-kernel-density-location.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/viglione-et-al-2013-kernel-density-location.png new file mode 100644 index 0000000..d832dec Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/viglione-et-al-2013-kernel-density-location.png differ diff --git a/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/viglione-et-al-2013-trace-location.png b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/viglione-et-al-2013-trace-location.png new file mode 100644 index 0000000..a6c8304 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/1-univariate-analysis/images/viglione-et-al-2013-trace-location.png differ diff --git a/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/1-bulletin17C-examples/bulletin-17c-examples.bestfit b/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/1-bulletin17C-examples/bulletin-17c-examples.bestfit index 4512b5f..8e37eaf 100644 Binary files a/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/1-bulletin17C-examples/bulletin-17c-examples.bestfit and b/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/1-bulletin17C-examples/bulletin-17c-examples.bestfit differ diff --git a/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/1-bulletin17C-examples/bulletin-17c-examples.md b/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/1-bulletin17C-examples/bulletin-17c-examples.md index 59bfce3..e6efe63 100644 --- a/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/1-bulletin17C-examples/bulletin-17c-examples.md +++ b/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/1-bulletin17C-examples/bulletin-17c-examples.md @@ -46,85 +46,71 @@ B17C-method fits of the seven Bulletin 17C example datasets, including both mult 3. Open `bulletin-17c-examples.bestfit`. ### Exploring the Elements - -For each B17C alternative: +For each B17C analysis: 1. Click the alternative in the Project Explorer. 2. Open the **Frequency** tab — the central LP-III curve plus the chosen confidence intervals are shown. -3. Switch the confidence-interval type in the Properties panel between **MVN** and **BCB** (Bias-Corrected Bootstrap) to compare. -4. Use the **Information Expansion** Properties pane to add or remove historical and paleoflood records. - -## Analysis Settings - -Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any alternative to inspect: - -- **Sampler type** (DEMCzs, ARWMH, HMC). -- **Iterations / Warm-up Iterations** — total post-warmup samples per chain. -- **Number of Chains** — typically 6 for routine work. -- **Thinning Interval** — keeps every Nth sample to reduce storage / autocorrelation. -- **Point Estimator** — Posterior Mean (default), Posterior Median, or Posterior Mode (MAP). -- **Credible Interval Width** — typically 0.90 or 0.95. +3. Switch the confidence-interval type in the **Properties** panel under Options between **MVN** and **BCB** (Bias-Corrected Bootstrap) to compare. ## Expected Results - - +Below are the expected results for B17C Analysis labeled "Example 1"; this should be the first analysis in the list. +Be sure to explore all of the analyses provided! ### Parameter Estimates +The parameter estimates are found under the **GMM Report** tab to the left as parameter summary statistics. - - -| Alternative | Parameter | Mean | Median | Lower CI | Upper CI | R-hat | ESS | +| Parameter | Mean | Std Dev | 5% | Median | 95% | |---|---|---|---|---|---|---|---| -| _(placeholder)_ | | | | | | | | +| Mean (of log) (µ) | 3.32859 | 0.0170513 | 3.30056 | 3.32859 | 3.35661 | +| Std Dev (of log) (σ) | 0.140591 | 0.0124871 | 0.120003 | 0.140536 | 0.161152 | +| Skew (of log) (γ) | 0.422345 | 0.214745 | 0.0703177 | 0.422267 | 0.774578 | ### Frequency / Quantile Table +While in the **Distribution Results** tab to the left, select Tabular Results to see the frequency plot's value at each return level probability, - - -| AEP (%) | Return Period (yr) | Median | Lower CI | Upper CI | +| Probability | 95.0% CI | 5.0% CI | Expected Probability | Computed | |---|---|---|---|---| -| 50 | 2 | | | | -| 10 | 10 | | | | -| 1 | 100 | | | | -| 0.5 | 200 | | | | -| 0.2 | 500 | | | | +| 1E-06 | 31536.45476960882 | 9504.478431532647 | 24554.49950471727 | 16637.381290694262 | +| 2E-06 | 28149.802168541166 | 9040.75064415998 | 21698.320005194113 | 15373.041485536076 | +| 5E-06 | 24160.94198954819 | 8453.443850597601 | 18465.22493642291 | 13822.796830244182 | +| 1E-05 | 21455.61220838344 | 8018.426746788033 | 16368.642332507934 | 12735.491236413278 | +| 2E-05 | 19059.420515419384 | 7584.834601256706 | 14529.108611032698 | 11716.700271971204 | +| 5E-05 | 16227.689492312738 | 7036.676121218768 | 12431.682956323782 | 10467.780043029716 | +| 0.0001 | 14352.979242152784 | 6646.968110248417 | 11061.167218506842 | 9591.790229464237 | +| 0.0002 | 12681.090740368469 | 6260.81983404009 | 9849.412895354815 | 8770.75246602347 | +| 0.0005 | 10739.197536045618 | 5748.645545945168 | 8454.21602532957 | 7763.446819612117 | +| 0.001 | 9456.728000321902 | 5377.2843046125 | 7532.75915104478 | 7055.894046242264 | +| 0.002 | 8302.127673152962 | 5008.506131955913 | 6707.646530666868 | 6391.361951623581 | +| 0.005 | 6950.922731163299 | 4521.195397698769 | 5743.428623397382 | 5572.971134836763 | +| 0.01 | 6048.389460148426 | 4162.263351862811 | 5093.009853602178 | 4994.660836353398 | +| 0.02 | 5228.424298909672 | 3799.8948635549073 | 4498.148210293506 | 4447.087767122384 | +| 0.05 | 4270.277948099271 | 3319.851153928296 | 3778.9736925918733 | 3762.259385065009 | +| 0.1 | 3624.548453911838 | 2945.4644456014116 | 3270.0420861902307 | 3265.250637410281 | +| 0.2 | 3018.199431766434 | 2549.418823517292 | 2774.225196097636 | 2774.0651594381807 | +| 0.3 | 2675.8403847879326 | 2299.9841323734913 | 2479.7934268715235 | 2480.5351134262696 | +| 0.5 | 2227.0001382334076 | 1948.8026579103694 | 2082.108332033603 | 2083.1343664241135 | +| 0.7 | 1889.0073300093154 | 1662.0699593897555 | 1770.3603956366273 | 1771.433478893447 | +| 0.8 | 1725.6343417562318 | 1515.1032598389882 | 1614.4240965923188 | 1615.5331366620323 | +| 0.9 | 1541.3255961148857 | 1335.0431447889257 | 1430.5903005331681 | 1432.0541875729045 | +| 0.95 | 1417.3600581301248 | 1203.0906894783586 | 1301.5522975174601 | 1304.365272636727 | +| 0.98 | 1305.492656087999 | 1068.6123887847205 | 1174.5910966211009 | 1181.8601363704101 | +| 0.99 | 1243.1832472499386 | 986.9285193815624 | 1097.7448455996291 | 1110.7760005372197 | ### Plots +There are also plenty of plots to explore our results with. Under the **Distribution Results** tab we have a frequency curve. -![Frequency curve (AEP versus quantile) for each alternative, with the credible band.](images/bulletin-17c-frequency.png) -*Figure: Frequency curve (AEP versus quantile) for each alternative, with the credible band.* +![Frequency curve (AEP versus quantile), with the credible band.](../images/bulletin-17c-frequency.png) -![Posterior kernel density for each parameter.](images/bulletin-17c-kernel-density.png) -*Figure: Posterior kernel density for each parameter.* +*Figure 1: Frequency curve (AEP versus quantile), with the credible band.* -![Markov-chain traces for each parameter.](images/bulletin-17c-trace.png) -*Figure: Markov-chain traces for each parameter.* +The **Kernal Density** tab shows an estimate for the pdf of each parameter. -![Autocorrelation function of the chains, used to estimate effective sample size.](images/bulletin-17c-autocorrelation.png) -*Figure: Autocorrelation function of the chains, used to estimate effective sample size.* +![Posterior kernel density for mean parameter (µ).](../images/bulletin-17c-kernel-density-mean.png) -### MCMC Diagnostics - -Verify chain convergence before interpreting any results: - -- **R-hat** — should be < 1.01 for every parameter. -- **Effective Sample Size (ESS)** — at least a few hundred per parameter. -- **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). -- **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. +*Figure 2: Posterior kernel density for mean parameter (µ).* ## Next Steps - Compare MVN-quantile and bias-corrected bootstrap (BCB) confidence intervals on the same dataset. - Re-run on the same input data using the **Bayesian Univariate** workflow and compare AEPs and confidence intervals. - Add a **regional skew** weighting if a regional skew estimate is available. - -## References - - - ---- - -_This tutorial was generated from the project's `.bestfit` file metadata. The narrative and figure / table sections are placeholders — capture screenshots from the BestFit GUI and paste output tables to complete the guide._ diff --git a/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/2-information-expansion/blakely-mountain-dam-b17c.bestfit b/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/2-information-expansion/blakely-mountain-dam-b17c.bestfit index e9fa5ae..919da8a 100644 Binary files a/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/2-information-expansion/blakely-mountain-dam-b17c.bestfit and b/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/2-information-expansion/blakely-mountain-dam-b17c.bestfit differ diff --git a/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/2-information-expansion/blakely-mountain-dam-b17c.md b/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/2-information-expansion/blakely-mountain-dam-b17c.md index 096a023..8c48634 100644 --- a/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/2-information-expansion/blakely-mountain-dam-b17c.md +++ b/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/2-information-expansion/blakely-mountain-dam-b17c.md @@ -47,85 +47,71 @@ B17C-method flood-frequency analysis for Blakely Mountain Dam, Arkansas. Demonst 3. Open `blakely-mountain-dam-b17c.bestfit`. ### Exploring the Elements +For each B17C analysis: -For each B17C alternative: - -1. Click the alternative in the Project Explorer. +1. Click the analysis in the Project Explorer. 2. Open the **Frequency** tab — the central LP-III curve plus the chosen confidence intervals are shown. 3. Switch the confidence-interval type in the Properties panel between **MVN** and **BCB** (Bias-Corrected Bootstrap) to compare. -4. Use the **Information Expansion** Properties pane to add or remove historical and paleoflood records. - -## Analysis Settings - -Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any alternative to inspect: - -- **Sampler type** (DEMCzs, ARWMH, HMC). -- **Iterations / Warm-up Iterations** — total post-warmup samples per chain. -- **Number of Chains** — typically 6 for routine work. -- **Thinning Interval** — keeps every Nth sample to reduce storage / autocorrelation. -- **Point Estimator** — Posterior Mean (default), Posterior Median, or Posterior Mode (MAP). -- **Credible Interval Width** — typically 0.90 or 0.95. ## Expected Results - - +Below are the expected results for B17C Analysis labeled "Systematic"; this should be the first analysis in the list. +Be sure to explore all of the analyses provided! ### Parameter Estimates +The parameter estimates are found under the **GMM Report** tab to the left as parameter summary statistics. - - -| Alternative | Parameter | Mean | Median | Lower CI | Upper CI | R-hat | ESS | +| Parameter | Mean | Std Dev | 5% | Median | 95% | |---|---|---|---|---|---|---|---| -| _(placeholder)_ | | | | | | | | +| Mean (of log) (µ) | 4.64664 | 0.0236085 | 4.60689 | 4.64724 | 4.68448 | +| Std Dev (of log) (σ) | 0.227804 | 0.0181184 | 0.201544 | 0.226036 | 0.260691 | +| Skew (of log) (γ) | -0.253436 | 0.278591 | -0.728621 | -0.243456 | 0.193487 | ### Frequency / Quantile Table +While in the **Distribution Results** tab to the left, select Tabular Results to see the frequency plot's value at each return level probability, - - -| AEP (%) | Return Period (yr) | Median | Lower CI | Upper CI | +| Probability | 95.0% CI | 5.0% CI | Expected Probability | Computed | |---|---|---|---|---| -| 50 | 2 | | | | -| 10 | 10 | | | | -| 1 | 100 | | | | -| 0.5 | 200 | | | | -| 0.2 | 500 | | | | +| 1E-06 | 758026.0567215704 | 170106.17166955775 | 647985.6785807601 | 337650.2931590468 | +| 2E-06 | 687457.3608267573 | 167933.4591347272 | 572980.2849303234 | 321974.30619051546 | +| 5E-06 | 605797.5173862581 | 164359.55052939 | 488427.35917153396 | 301361.24571106234 | +| 1E-05 | 546896.4929631923 | 161574.43687964996 | 433787.67847244337 | 285854.5761315717 | +| 2E-05 | 495136.2355250269 | 158260.77686168702 | 385919.11999473925 | 270425.0762090789 | +| 5E-05 | 430765.4611260562 | 153761.68815122006 | 331416.23129463074 | 250149.65834840835 | +| 0.0001 | 386524.5324815373 | 149858.91059987794 | 295808.22312915954 | 234904.55681712108 | +| 0.0002 | 345920.5247566132 | 145633.02421622866 | 264274.20982495 | 219738.59330979967 | +| 0.0005 | 296392.18815290864 | 139067.20193665382 | 227848.20054746873 | 199807.21091061027 | +| 0.001 | 262925.86683040817 | 133645.6929320698 | 203645.2496070585 | 184811.1433395044 | +| 0.002 | 231197.8330765486 | 127380.98625304602 | 181837.30076821716 | 169874.6444131373 | +| 0.005 | 193750.60818969348 | 118585.84929856933 | 156026.86778769732 | 150193.19373174553 | +| 0.01 | 167810.73511495857 | 110938.93577506686 | 138321.16547542924 | 135318.4089210235 | +| 0.02 | 144060.67734699778 | 102158.4833428134 | 121771.92572264813 | 120406.6551113714 | +| 0.05 | 115220.06936697957 | 88687.80419613553 | 100974.16632702298 | 100503.7235452781 | +| 0.1 | 95266.65947138361 | 76688.56825309672 | 85416.84921379967 | 85115.03654527031 | +| 0.2 | 76463.27125700287 | 62694.82939448162 | 69320.57812048237 | 69098.29086959193 | +| 0.3 | 65247.42053848779 | 53681.62774823276 | 59299.88639259649 | 59158.993978823855 | +| 0.5 | 50039.98323082939 | 40940.568575556485 | 45337.65867614697 | 45341.52011821188 | +| 0.7 | 37937.09940381622 | 30814.594915999118 | 34249.709753992225 | 34346.215404511764 | +| 0.8 | 32099.653846141453 | 25599.78162225028 | 28742.99026062168 | 28867.47121462463 | +| 0.9 | 25609.52171376839 | 19324.504161574154 | 22360.60024096732 | 22520.537709704982 | +| 0.95 | 21372.58064185311 | 14981.065839501001 | 18006.187755721705 | 18227.54858386635 | +| 0.98 | 17610.804373728533 | 10927.222765274915 | 13906.278498730422 | 14265.442755390326 | +| 0.99 | 15534.709009938304 | 8701.537506635772 | 11567.783109782977 | 12064.31455262698 | ### Plots +There are also plenty of plots to explore our results with. Under the **Distribution Results** tab we have a frequency curve. -![Frequency curve (AEP versus quantile) for each alternative, with the credible band.](images/blakely-b17c-frequency.png) -*Figure: Frequency curve (AEP versus quantile) for each alternative, with the credible band.* +![Frequency curve (AEP versus quantile), with the credible band.](../images/blakely-b17c-frequency.png) -![Posterior kernel density for each parameter.](images/blakely-b17c-kernel-density.png) -*Figure: Posterior kernel density for each parameter.* +*Figure 1: Frequency curve (AEP versus quantile) for each alternative, with the credible band.* -![Markov-chain traces for each parameter.](images/blakely-b17c-trace.png) -*Figure: Markov-chain traces for each parameter.* +The **Kernal Density** tab shows an estimate for the pdf of each parameter. -![Autocorrelation function of the chains, used to estimate effective sample size.](images/blakely-b17c-autocorrelation.png) -*Figure: Autocorrelation function of the chains, used to estimate effective sample size.* +![Posterior kernel density for mean parameter (µ).](../images/blakely-b17c-kernel-density-mean.png) -### MCMC Diagnostics - -Verify chain convergence before interpreting any results: - -- **R-hat** — should be < 1.01 for every parameter. -- **Effective Sample Size (ESS)** — at least a few hundred per parameter. -- **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). -- **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. +*Figure 2: Posterior kernel density for mean parameter (µ).* ## Next Steps - Compare MVN-quantile and bias-corrected bootstrap (BCB) confidence intervals on the same dataset. - Re-run on the same input data using the **Bayesian Univariate** workflow and compare AEPs and confidence intervals. -- Add a **regional skew** weighting if a regional skew estimate is available. - -## References - - - ---- - -_This tutorial was generated from the project's `.bestfit` file metadata. The narrative and figure / table sections are placeholders — capture screenshots from the BestFit GUI and paste output tables to complete the guide._ +- Add a **regional skew** weighting if a regional skew estimate is available. \ No newline at end of file diff --git a/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/3-measurement-errors/README.txt b/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/3-measurement-errors/README.txt deleted file mode 100644 index 951532b..0000000 --- a/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/3-measurement-errors/README.txt +++ /dev/null @@ -1,3 +0,0 @@ -Measurement Errors: - --This example demonstrates how to incorporate measurement errors (or prediction errors) derived from a MOVE.3 analysis. \ No newline at end of file diff --git a/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/3-measurement-errors/sinnemahoning-move3-b17c.bestfit b/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/3-measurement-errors/sinnemahoning-move3-b17c.bestfit index b9bab29..2dabb81 100644 Binary files a/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/3-measurement-errors/sinnemahoning-move3-b17c.bestfit and b/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/3-measurement-errors/sinnemahoning-move3-b17c.bestfit differ diff --git a/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/3-measurement-errors/sinnemahoning-move3-b17c.md b/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/3-measurement-errors/sinnemahoning-move3-b17c.md index cf929d3..c550877 100644 --- a/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/3-measurement-errors/sinnemahoning-move3-b17c.md +++ b/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/3-measurement-errors/sinnemahoning-move3-b17c.md @@ -40,84 +40,71 @@ B17C-method flood-frequency analysis for Sinnemahoning Creek (USGS gage 01543500 ### Exploring the Elements -For each B17C alternative: +For each B17C analysis: -1. Click the alternative in the Project Explorer. +1. Click the analysis in the Project Explorer. 2. Open the **Frequency** tab — the central LP-III curve plus the chosen confidence intervals are shown. 3. Switch the confidence-interval type in the Properties panel between **MVN** and **BCB** (Bias-Corrected Bootstrap) to compare. -4. Use the **Information Expansion** Properties pane to add or remove historical and paleoflood records. - -## Analysis Settings - -Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any alternative to inspect: - -- **Sampler type** (DEMCzs, ARWMH, HMC). -- **Iterations / Warm-up Iterations** — total post-warmup samples per chain. -- **Number of Chains** — typically 6 for routine work. -- **Thinning Interval** — keeps every Nth sample to reduce storage / autocorrelation. -- **Point Estimator** — Posterior Mean (default), Posterior Median, or Posterior Mode (MAP). -- **Credible Interval Width** — typically 0.90 or 0.95. ## Expected Results - - +Below are the expected results for B17C Analysis labeled "B17C - LPIII - No Extension"; this should be the first analysis in the list. +Be sure to explore all of the analyses provided! ### Parameter Estimates +The parameter estimates are found under the **GMM Report** tab to the left as parameter summary statistics. - - -| Alternative | Parameter | Mean | Median | Lower CI | Upper CI | R-hat | ESS | +| Parameter | Mean | Std Dev | 5% | Median | 95% | |---|---|---|---|---|---|---|---| -| _(placeholder)_ | | | | | | | | +| Mean (of log) (µ) | 4.12907 | 0.0217382 | 4.09443 | 4.1284 | 4.16586 | +| Std Dev (of log) (σ) | 0.194461 | 0.017288 | 0.169784 | 0.192373 | 0.225954 | +| Skew (of log) (γ) | 0.394872 | 0.370758 | -0.0801297 | 0.325077 | 1.11069 | ### Frequency / Quantile Table +While in the **Distribution Results** tab to the left, select Tabular Results to see the frequency plot's value at each return level probability, - - -| AEP (%) | Return Period (yr) | Median | Lower CI | Upper CI | +| Probability | 95.0% CI | 5.0% CI | Expected Probability | Computed | |---|---|---|---|---| -| 50 | 2 | | | | -| 10 | 10 | | | | -| 1 | 100 | | | | -| 0.5 | 200 | | | | -| 0.2 | 500 | | | | +| 1E-06 | 1010667.4196454879 | 87278.89808161247 | 888023.2521845531 | 189358.8687011805 | +| 2E-06 | 825694.3822362763 | 82912.68590135279 | 662692.7488685393 | 171814.47275785723 | +| 5E-06 | 628451.1410449261 | 76873.00488312499 | 457567.26485387725 | 150699.54835185735 | +| 1E-05 | 511113.5866934283 | 72516.31829703723 | 350321.67281641084 | 136173.00230633706 | +| 2E-05 | 415539.53913432173 | 68161.97643385472 | 271376.23746867385 | 122791.94048634727 | +| 5E-05 | 316779.5426404807 | 62523.183960320865 | 197231.4428742737 | 106718.84884731137 | +| 0.0001 | 257705.018127259 | 58466.244656610834 | 157112.99805686 | 95682.12342781319 | +| 0.0002 | 208859.17060148393 | 54467.605524915816 | 126648.2013367339 | 85531.57282856839 | +| 0.0005 | 157692.52769288246 | 49242.15006188284 | 96889.38679515879 | 73358.75619457685 | +| 0.001 | 127244.4630291779 | 45495.29838709207 | 80038.99553705836 | 65011.35208586299 | +| 0.002 | 102180.48874505726 | 41728.86854976766 | 66661.81486476627 | 57339.64782094964 | +| 0.005 | 76243.52857440646 | 36926.027495256545 | 52819.36685268229 | 48139.26413690107 | +| 0.01 | 60873.489791151405 | 33375.66551625586 | 44442.95904045988 | 41820.97141250052 | +| 0.02 | 48326.106950837464 | 29779.872291720047 | 37368.829469010976 | 35994.71403686458 | +| 0.05 | 35451.46898338216 | 25031.918185260154 | 29455.157863770197 | 28948.923594247586 | +| 0.1 | 27930.858451509157 | 21367.865649365885 | 24222.10102612838 | 24026.28824969158 | +| 0.2 | 21689.640353267652 | 17442.808807064896 | 19382.689188020217 | 19343.430705928662 | +| 0.3 | 18433.819974994873 | 15035.21364288901 | 16628.347175602434 | 16643.134623824022 | +| 0.5 | 14353.683830195841 | 11893.008361180213 | 13064.570383845343 | 13121.330872603865 | +| 0.7 | 11437.283886163019 | 9572.280888598843 | 10431.182312148563 | 10482.326646093956 | +| 0.8 | 10048.434355793785 | 8425.432791472093 | 9185.27342941452 | 9208.686126838204 | +| 0.9 | 8609.348757548101 | 7028.487485163489 | 7782.223358042681 | 7753.87601295728 | +| 0.95 | 7779.612293112392 | 6011.705176932596 | 6813.691675726118 | 6772.147976123263 | +| 0.98 | 7137.323270176243 | 5022.286857330054 | 5855.705800187188 | 5856.10461452967 | +| 0.99 | 6816.267686757423 | 4444.811201588628 | 5276.8069213907975 | 5336.962866943537 | ### Plots +There are also plenty of plots to explore our results with. Under the **Distribution Results** tab we have a frequency curve. -![Frequency curve (AEP versus quantile) for each alternative, with the credible band.](images/sinnemahoning-b17c-frequency.png) -*Figure: Frequency curve (AEP versus quantile) for each alternative, with the credible band.* - -![Posterior kernel density for each parameter.](images/sinnemahoning-b17c-kernel-density.png) -*Figure: Posterior kernel density for each parameter.* +![Frequency curve (AEP versus quantile) for each alternative, with the credible band.](../images/sinnemahoning-b17c-frequency.png) -![Markov-chain traces for each parameter.](images/sinnemahoning-b17c-trace.png) -*Figure: Markov-chain traces for each parameter.* +*Figure 1: Frequency curve (AEP versus quantile) for each alternative, with the credible band.* -![Autocorrelation function of the chains, used to estimate effective sample size.](images/sinnemahoning-b17c-autocorrelation.png) -*Figure: Autocorrelation function of the chains, used to estimate effective sample size.* +The **Kernal Density** tab shows an estimate for the pdf of each parameter. -### MCMC Diagnostics +![Posterior kernel density for mean parameter (µ).](../images/sinnemahoning-b17c-kernel-density-mean.png) -Verify chain convergence before interpreting any results: - -- **R-hat** — should be < 1.01 for every parameter. -- **Effective Sample Size (ESS)** — at least a few hundred per parameter. -- **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). -- **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. +*Figure 2: Posterior kernel density for mean parameter (µ).* ## Next Steps - Compare MVN-quantile and bias-corrected bootstrap (BCB) confidence intervals on the same dataset. - Re-run on the same input data using the **Bayesian Univariate** workflow and compare AEPs and confidence intervals. - Add a **regional skew** weighting if a regional skew estimate is available. - -## References - - - ---- - -_This tutorial was generated from the project's `.bestfit` file metadata. The narrative and figure / table sections are placeholders — capture screenshots from the BestFit GUI and paste output tables to complete the guide._ diff --git a/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/images/blakely-b17c-frequency.png b/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/images/blakely-b17c-frequency.png new file mode 100644 index 0000000..68c2485 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/images/blakely-b17c-frequency.png differ diff --git a/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/images/blakely-b17c-kernel-density-mean.png b/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/images/blakely-b17c-kernel-density-mean.png new file mode 100644 index 0000000..4469591 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/images/blakely-b17c-kernel-density-mean.png differ diff --git a/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/images/bulletin-17c-frequency.png b/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/images/bulletin-17c-frequency.png new file mode 100644 index 0000000..395481e Binary files /dev/null and b/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/images/bulletin-17c-frequency.png differ diff --git a/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/images/bulletin-17c-kernel-density-mean.png b/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/images/bulletin-17c-kernel-density-mean.png new file mode 100644 index 0000000..5a5d1f0 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/images/bulletin-17c-kernel-density-mean.png differ diff --git a/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/images/sinnemahoning-b17c-frequency.png b/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/images/sinnemahoning-b17c-frequency.png new file mode 100644 index 0000000..4b892c5 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/images/sinnemahoning-b17c-frequency.png differ diff --git a/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/images/sinnemahoning-b17c-kernel-density-mean.png b/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/images/sinnemahoning-b17c-kernel-density-mean.png new file mode 100644 index 0000000..e9c4f97 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/2-bulletin-17C-analysis/images/sinnemahoning-b17c-kernel-density-mean.png differ diff --git a/examples/4-univariate-distribution-analysis/3-point-process-analysis/point-process-examples.bestfit b/examples/4-univariate-distribution-analysis/3-point-process-analysis/point-process-examples.bestfit index 1bb422c..0018caf 100644 Binary files a/examples/4-univariate-distribution-analysis/3-point-process-analysis/point-process-examples.bestfit and b/examples/4-univariate-distribution-analysis/3-point-process-analysis/point-process-examples.bestfit differ diff --git a/examples/4-univariate-distribution-analysis/3-point-process-analysis/point-process-examples.md b/examples/4-univariate-distribution-analysis/3-point-process-analysis/point-process-examples.md index 4752fab..5d8da64 100644 --- a/examples/4-univariate-distribution-analysis/3-point-process-analysis/point-process-examples.md +++ b/examples/4-univariate-distribution-analysis/3-point-process-analysis/point-process-examples.md @@ -47,9 +47,9 @@ Peaks-over-threshold (POT) modeling using non-homogeneous Poisson point processe ### Exploring the Elements -For each Point Process alternative: +For each Point Process analysis: -1. Click the alternative in the Project Explorer. +1. Click the analysis in the Project Explorer. 2. Open the **Frequency** tab to view the AEP curve derived from the fitted intensity function. 3. Compare against the **GEV block-maximum** alternative on the same record. 4. For seasonal point processes, inspect the rate function over the annual cycle. @@ -66,65 +66,86 @@ Each Bayesian analysis in this project uses the DEMCzs sampler with project-spec - **Credible Interval Width** — typically 0.90 or 0.95. ## Expected Results - - +Below are the expected results for Point Process Analysis labeled "USC00040741 - Point Process"; this should be the first analysis in the list. +Be sure to explore all of the analyses provided! ### Parameter Estimates +The parameter estimates are found under the **MCMC Report** tab to the left as parameter summary statistics. - - -| Alternative | Parameter | Mean | Median | Lower CI | Upper CI | R-hat | ESS | +| Parameter | Mean | Std Dev | 5% | Median | 95% |R-hat | ESS | |---|---|---|---|---|---|---|---| -| _(placeholder)_ | | | | | | | | +| Location (ξ) | 2.36446 | 0.119512 | 2.17884 | 2.35997 | 2.56968 | 0.9998 | 9299 | +| Scale (α) | 1.1211 | 0.0890772 | 0.988996 | 1.11566 | 1.27624 | 1.0001 | 9452 | +| Shape (κ) | -0.132656 | 0.0679166 | -0.250412 | -0.128314 | -0.0296323 | 1.0002 | 9655 | ### Frequency / Quantile Table +While in the **Distribution Results** tab to the left, select Tabular Results to see the frequency plot's value at each return level probability, - - -| AEP (%) | Return Period (yr) | Median | Lower CI | Upper CI | +| Probability | 95.0% CI | 5.0% CI | Posterior Predictive| Posterior Mean | |---|---|---|---|---| -| 50 | 2 | | | | -| 10 | 10 | | | | -| 1 | 100 | | | | -| 0.5 | 200 | | | | -| 0.2 | 500 | | | | +| 1E-06 | 150.84742737241032 | 20.653979425471444 | 118.64024523334363 | 46.7397957632871 | +| 2E-06 | 126.36944349162967 | 19.546371503627217 | 94.81941905017696 | 42.099022259113205 | +| 5E-06 | 100.24184536687025 | 18.122746805249296 | 71.29990628356329 | 36.58394425811294 | +| 1E-05 | 83.95977937371478 | 17.05293749465014 | 57.94724500771058 | 32.83534514226579 | +| 2E-05 | 69.99612120141246 | 15.992409439227242 | 47.41944026371997 | 29.41604706697312 | +| 5E-05 | 55.255274556819735 | 14.64347424419414 | 36.74132263154507 | 25.352537238078842 | +| 0.0001 | 46.14234693981825 | 13.65581705014883 | 30.505369026003066 | 22.59052678246136 | +| 0.0002 | 38.41303546097958 | 12.655700558655765 | 25.46553900386915 | 20.071078507880806 | +| 0.0005 | 30.057464804325864 | 11.385035786594663 | 20.204697475682224 | 17.07674290064117 | +| 0.001 | 24.911630438443996 | 10.44583441542861 | 17.036302326564794 | 15.04114888110213 | +| 0.002 | 20.51019183389008 | 9.542945332733689 | 14.40380614941757 | 13.183801619839143 | +| 0.005 | 15.812371222605194 | 8.362681989850216 | 11.558593508979538 | 10.97480093075537 | +| 0.01 | 12.879593110421727 | 7.505224291199614 | 9.776332964052276 | 9.470766350191022 | +| 0.02 | 10.46497115795248 | 6.639410491573149 | 8.236700760100655 | 8.094524352155947 | +| 0.05 | 7.842946001602478 | 5.517392191102903 | 6.483370080771518 | 6.445702646629233 | +| 0.1 | 6.177040717516899 | 4.667457792424369 | 5.3114482136768 | 5.3043503691108835 | +| 0.2 | 4.7403199750165586 | 3.806013007347718 | 4.221888392945112 | 4.225001004399712 | +| 0.3 | 3.9812707798818154 | 3.2813687340211 | 3.5982540068529874 | 3.602988811768916 | +| 0.5 | 3.0340724951059537 | 2.559296911433748 | 2.7799484304483886 | 2.7855044187904583 | +| 0.7 | 2.3451789920629706 | 1.9893989044219564 | 2.1526838875417478 | 2.158890695863173 | +| 0.8 | 2.00515709772634 | 1.7014038001299205 | 1.8410610349876277 | 1.8474328607209767 | +| 0.9 | 1.6050129281077634 | 1.3625560915017505 | 1.4732448309439914 | 1.4792931120449715 | +| 0.95 | 1.3268729985339036 | 1.1182551063325952 | 1.2143033558814498 | 1.2197266540063072 | +| 0.98 | 1.0634446975101701 | 0.8679460645015797 | 0.960578974786177 | 0.9655937519053599 | +| 0.99 | 0.911384148668507 | 0.7125284717251967 | 0.8091127253526231 | 0.8146247420912087 | ### Plots +There are also plenty of plots to explore our results with. Under the **Distribution Results** tab we have a frequency curve. -![Frequency curve (AEP versus quantile) for each alternative, with the credible band.](images/point-process-frequency.png) -*Figure: Frequency curve (AEP versus quantile) for each alternative, with the credible band.* +![Frequency curve (AEP versus quantile), with the credible band.](../images/point-process-frequency.png) -![Posterior kernel density for each parameter.](images/point-process-kernel-density.png) -*Figure: Posterior kernel density for each parameter.* +*Figure 1: Frequency curve (AEP versus quantile), with the credible band.* -![Markov-chain traces for each parameter.](images/point-process-trace.png) -*Figure: Markov-chain traces for each parameter.* +The **Kernal Density** tab shows an estimate for the pdf of each parameter. -![Autocorrelation function of the chains, used to estimate effective sample size.](images/point-process-autocorrelation.png) -*Figure: Autocorrelation function of the chains, used to estimate effective sample size.* +![Posterior kernel density for location parameter (ξ).](../images/point-process-kernel-density-location.png) -### MCMC Diagnostics +*Figure 2: Posterior kernel density for location parameter (ξ).* + +The **Markov Chain Traces** tab explores the traces of each Markov chain as it explores the posterior space in order to converge. + +![Markov-chain traces for location parameter (ξ).](../images/point-process-trace-location.png) + +*Figure 3: Markov-chain traces for location parameter (ξ).* + +Finally, we can investigate the autocorrelation of the chains under the **Autocorrelation** tab. + +![Autocorrelation function of the chains, used to estimate effective sample size, for location parameter (ξ).](../images/point-process-autocorrelation-location.png) -Verify chain convergence before interpreting any results: +*Figure 4: Autocorrelation function of the chains, used to estimate effective sample size, for location parameter (ξ).* + +### MCMC Diagnostics +One should always verify chain convergence before interpreting any results. There are a variety of ways including: - **R-hat** — should be < 1.01 for every parameter. - **Effective Sample Size (ESS)** — at least a few hundred per parameter. - **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). - **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. +These can be found under the **Markov Chain Traces** and **MCMC Reports** tabs. + ## Next Steps - Compare the **Point Process** AEP curve to the **GEV block-maximum** AEP curve on the same record. - Add a **seasonal** sinusoidal-rate point process to capture annual-cycle clustering. -- Compute **expected number of exceedances** above engineering thresholds from the fitted intensity. - -## References - - - ---- - -_This tutorial was generated from the project's `.bestfit` file metadata. The narrative and figure / table sections are placeholders — capture screenshots from the BestFit GUI and paste output tables to complete the guide._ +- Compute **expected number of exceedances** above engineering thresholds from the fitted intensity. \ No newline at end of file diff --git a/examples/4-univariate-distribution-analysis/4-mixture-analysis/mixture-distribution-examples.bestfit b/examples/4-univariate-distribution-analysis/4-mixture-analysis/mixture-distribution-examples.bestfit index 80972c0..2a8ba9b 100644 Binary files a/examples/4-univariate-distribution-analysis/4-mixture-analysis/mixture-distribution-examples.bestfit and b/examples/4-univariate-distribution-analysis/4-mixture-analysis/mixture-distribution-examples.bestfit differ diff --git a/examples/4-univariate-distribution-analysis/4-mixture-analysis/mixture-distribution-examples.md b/examples/4-univariate-distribution-analysis/4-mixture-analysis/mixture-distribution-examples.md index 04dd0de..affe0bc 100644 --- a/examples/4-univariate-distribution-analysis/4-mixture-analysis/mixture-distribution-examples.md +++ b/examples/4-univariate-distribution-analysis/4-mixture-analysis/mixture-distribution-examples.md @@ -32,9 +32,9 @@ Mixture-distribution fitting on synthetic samples from two- and three-component ### Exploring the Elements -For each Mixture Distribution alternative: +For each Mixture Distribution analysis: -1. Click the alternative in the Project Explorer. +1. Click the analysis in the Project Explorer. 2. Open the **Frequency** tab to view the mixture AEP curve. 3. Open the **Kernel Density** tab to see the component contributions. 4. Inspect the component **weights** in the parameter table. @@ -51,65 +51,89 @@ Each Bayesian analysis in this project uses the DEMCzs sampler with project-spec - **Credible Interval Width** — typically 0.90 or 0.95. ## Expected Results - - +Below are the expected results for Mixture Distribution Analysis labeled "Mixture Distribution - 2 Normals"; this should be the first analysis in the list. +Be sure to explore all of the analyses provided! ### Parameter Estimates +The parameter estimates are found under the **MCMC Report** tab to the left as parameter summary statistics. - - -| Alternative | Parameter | Mean | Median | Lower CI | Upper CI | R-hat | ESS | +| Parameter | Mean | Std Dev | 5% | Median | 95% |R-hat | ESS | |---|---|---|---|---|---|---|---| -| _(placeholder)_ | | | | | | | | +| Weight (w₁) | 0.43411 | 0.0499398 | 0.35371 | 0.43398 | 0.517628 | 1.0001 | 9580 | +| Weight (w₂) | 0.56589 | 0.0499398 | 0.482372 | 0.56602 | 0.64629 | 1.0001 | 9580 | +| D1 Mean (µ) | 52.201 | 1.52931 | 49.6879 | 52.187 | 54.697 | 0.9999 | 9557 | +| D1 Std Dev (σ) | 9.54152 | 1.24415 | 7.80937 | 9.39534 | 11.7894 | 1.0001 | 9320 | +| D2 Mean (µ) | 98.6504 | 0.964829 | 97.0639 | 98.6506 | 100.232 | 0.9998 | 9453 | +| D2 Std Dev (σ) | 6.9293 | 0.713777 | 5.85081 | 6.87941 | 8.18494 | 0.9999 | 9483 | ### Frequency / Quantile Table +While in the **Distribution Results** tab to the left, select Tabular Results to see the frequency plot's value at each return level probability, - - -| AEP (%) | Return Period (yr) | Median | Lower CI | Upper CI | +| Probability | 95.0% CI | 5.0% CI | Posterior Predictive| Posterior Mean | |---|---|---|---|---| -| 50 | 2 | | | | -| 10 | 10 | | | | -| 1 | 100 | | | | -| 0.5 | 200 | | | | -| 0.2 | 500 | | | | +| 1E-06 | 136.75372915852546 | 125.65133645719423 | 134.61185390947912 | 130.78181474750846 | +| 2E-06 | 135.58073569847977 | 124.79515711696713 | 133.19862668833534 | 129.77408762157407 | +| 5E-06 | 133.95869233068584 | 123.62697987699049 | 131.33256895705728 | 128.39401059535456 | +| 1E-05 | 132.69501530956938 | 122.71012904948113 | 129.89756975501072 | 127.30986579366626 | +| 2E-05 | 131.38348587286313 | 121.75069448098422 | 128.4709197177208 | 126.18715719817294 | +| 5E-05 | 129.5650651108252 | 120.42575604874273 | 126.51989180832592 | 124.63641490461667 | +| 0.0001 | 128.13753808909365 | 119.3572618537595 | 125.03232531132672 | 123.40610894756115 | +| 0.0002 | 126.63343094477321 | 118.25177714123468 | 123.48097081763129 | 122.11924524529803 | +| 0.0005 | 124.50723352060287 | 116.70777645689547 | 121.38827096629753 | 120.31696506884354 | +| 0.001 | 122.79427068524714 | 115.45629403460369 | 119.71974776832967 | 118.86305456285493 | +| 0.002 | 121.0051513022824 | 114.11525846597938 | 117.98884192018699 | 117.31510407143973 | +| 0.005 | 118.44920146648148 | 112.17564493248561 | 115.54286475081985 | 115.08966168794181 | +| 0.01 | 116.30278497803258 | 110.55340632974699 | 113.54128069394946 | 113.23244939896003 | +| 0.02 | 113.94777125674857 | 108.74275323892348 | 111.3664585667642 | 111.17502743461085 | +| 0.05 | 110.36349207096862 | 105.89005804692832 | 108.0839174676419 | 108.01146265042512 | +| 0.1 | 107.14641466859999 | 103.14644079885251 | 105.09505613186427 | 105.08050613808324 | +| 0.2 | 103.12569093619203 | 99.35563682289323 | 101.23522291079722 | 101.2563910099315 | +| 0.3 | 100.05392742151857 | 95.86572492828353 | 98.07787536496916 | 98.12639534181538 | +| 0.5 | 94.01317508473839 | 69.84654815900699 | 90.20936874256606 | 90.38462908765455 | +| 0.7 | 62.73048414224994 | 53.151555799710934 | 56.9698032982063 | 56.96112581442284 | +| 0.8 | 54.78707935545491 | 48.2099778434261 | 51.25750156846604 | 51.2598562511874 | +| 0.9 | 48.27254901459952 | 41.99874320655629 | 45.15057731291054 | 45.16248186783007 | +| 0.95 | 44.080092523241184 | 37.11857035817384 | 40.6707615171922 | 40.756514288977925 | +| 0.98 | 39.92635171208513 | 31.66740897271099 | 35.85114540734791 | 36.13115451477489 | +| 0.99 | 37.320274047871976 | 28.171415415536107 | 32.672620413882406 | 33.16815581439024 | ### Plots +There are also plenty of plots to explore our results with. Under the **Distribution Results** tab we have a frequency curve. -![Frequency curve (AEP versus quantile) for each alternative, with the credible band.](images/mixture-frequency.png) -*Figure: Frequency curve (AEP versus quantile) for each alternative, with the credible band.* +![Frequency curve (AEP versus quantile), with the credible band.](../images/mixture-frequency.png) -![Posterior kernel density for each parameter.](images/mixture-kernel-density.png) -*Figure: Posterior kernel density for each parameter.* +*Figure 1: Frequency curve (AEP versus quantile), with the credible band.* -![Markov-chain traces for each parameter.](images/mixture-trace.png) -*Figure: Markov-chain traces for each parameter.* +The **Kernal Density** tab shows an estimate for the pdf of each parameter. -![Autocorrelation function of the chains, used to estimate effective sample size.](images/mixture-autocorrelation.png) -*Figure: Autocorrelation function of the chains, used to estimate effective sample size.* +![Posterior kernel density for weight parameter (w₁).](../images/mixture-kernel-density-w1.png) -### MCMC Diagnostics +*Figure 2: Posterior kernel density for weight parameter (w₁).* + +The **Markov Chain Traces** tab explores the traces of each Markov chain as it explores the posterior space in order to converge. + +![Markov-chain traces for weight parameter (w₁).](../images/mixture-trace-w1.png) + +*Figure 3: Markov-chain traces for weight parameter (w₁).* + +Finally, we can investigate the autocorrelation of the chains under the **Autocorrelation** tab. + +![Autocorrelation function of the chains, used to estimate effective sample size, for weight parameter (w₁).](../images/mixture-autocorrelation-w1.png) -Verify chain convergence before interpreting any results: +*Figure 4: Autocorrelation function of the chains, used to estimate effective sample size, for weight parameter (w₁).* + +### MCMC Diagnostics +One should always verify chain convergence before interpreting any results. There are a variety of ways including: - **R-hat** — should be < 1.01 for every parameter. - **Effective Sample Size (ESS)** — at least a few hundred per parameter. - **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). - **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. +These can be found under the **Markov Chain Traces** and **MCMC Reports** tabs. + ## Next Steps - Compare 2-component versus 3-component mixtures via DIC / WAIC. - Use a **zero-inflated** variant if the data has many true zeros (e.g., dry-day precipitation). - Visualize component memberships via the kernel-density plot. - -## References - - - ---- - -_This tutorial was generated from the project's `.bestfit` file metadata. The narrative and figure / table sections are placeholders — capture screenshots from the BestFit GUI and paste output tables to complete the guide._ diff --git a/examples/4-univariate-distribution-analysis/5-composite-analysis/mixed-population-examples.bestfit b/examples/4-univariate-distribution-analysis/5-composite-analysis/mixed-population-examples.bestfit index 9cd6ea5..8c8b12e 100644 Binary files a/examples/4-univariate-distribution-analysis/5-composite-analysis/mixed-population-examples.bestfit and b/examples/4-univariate-distribution-analysis/5-composite-analysis/mixed-population-examples.bestfit differ diff --git a/examples/4-univariate-distribution-analysis/5-composite-analysis/mixed-population-examples.md b/examples/4-univariate-distribution-analysis/5-composite-analysis/mixed-population-examples.md index 0b93a44..1850e50 100644 --- a/examples/4-univariate-distribution-analysis/5-composite-analysis/mixed-population-examples.md +++ b/examples/4-univariate-distribution-analysis/5-composite-analysis/mixed-population-examples.md @@ -43,16 +43,16 @@ Composite-distribution analysis on a synthetic mixed-population annual maximum s ### Exploring the Elements -For each Composite Distribution alternative: +For each Composite Distribution analysis: -1. Click the alternative in the Project Explorer. +1. Click the analysis in the Project Explorer. 2. Inspect the underlying univariate fits in the Properties panel. 3. Open the **Frequency** tab to view the combined AEP curve. 4. Switch between **competing-risks** and **AMS-mixture** formulations in the Properties panel. ## Analysis Settings -Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any alternative to inspect: +Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any Univariate Distribution analysis to inspect: - **Sampler type** (DEMCzs, ARWMH, HMC). - **Iterations / Warm-up Iterations** — total post-warmup samples per chain. @@ -61,65 +61,50 @@ Each Bayesian analysis in this project uses the DEMCzs sampler with project-spec - **Point Estimator** — Posterior Mean (default), Posterior Median, or Posterior Mode (MAP). - **Credible Interval Width** — typically 0.90 or 0.95. -## Expected Results - - - -### Parameter Estimates - - +** These are applicable for the underlying univariate fits of the Composite distribution. -| Alternative | Parameter | Mean | Median | Lower CI | Upper CI | R-hat | ESS | -|---|---|---|---|---|---|---|---| -| _(placeholder)_ | | | | | | | | +## Expected Results +Below are the expected results for Composite Distribution Analysis labeled "Competing Flood Types"; this should be the first analysis in the list. +Be sure to explore all of the analyses provided! ### Frequency / Quantile Table - - -| AEP (%) | Return Period (yr) | Median | Lower CI | Upper CI | +| Probability | 95.0% CI | 5.0% CI | Posterior Predictive| Posterior Mean | |---|---|---|---|---| -| 50 | 2 | | | | -| 10 | 10 | | | | -| 1 | 100 | | | | -| 0.5 | 200 | | | | -| 0.2 | 500 | | | | +| 1E-06 | 74519.59307634977 | 23043.055438711253 | 53303.584930385914 | 40328.58386704339 | +| 2E-06 | 63442.28519767511 | 20268.060906603358 | 45029.42488692156 | 34909.87670966961 | +| 5E-06 | 50914.48645228911 | 16974.060656020087 | 35838.51757068133 | 28659.534842755424 | +| 1E-05 | 42843.634535167774 | 14792.22896913906 | 30019.28503763235 | 24551.98452627458 | +| 2E-05 | 35908.527087533264 | 12828.205673568604 | 25036.26707200655 | 20923.846079998413 | +| 5E-05 | 28048.99451018836 | 10534.258991049504 | 19547.504838719167 | 16786.38278909963 | +| 0.0001 | 23081.73989316945 | 8995.933633012783 | 16105.001908264609 | 14101.431069518803 | +| 0.0002 | 18861.133012417908 | 7646.577492179918 | 13183.256813881462 | 11757.728877702602 | +| 0.0005 | 14228.218621849359 | 6085.705908858995 | 10001.430584816675 | 9124.862745391687 | +| 0.001 | 11343.735909792236 | 5067.628171433932 | 8031.639382544441 | 7444.962994075842 | +| 0.002 | 8924.895798801233 | 4187.721317001647 | 6380.730625837227 | 6002.117429686751 | +| 0.005 | 6349.87637683161 | 3183.03089865489 | 4612.796107299864 | 4415.175678512231 | +| 0.01 | 4802.169821451778 | 2551.699339431311 | 3541.214427680541 | 3428.252606019993 | +| 0.02 | 3532.011050213143 | 2029.6637300564416 | 2668.168860680768 | 2607.333508975283 | +| 0.05 | 2258.2076977477786 | 1489.7071923023445 | 1801.8721932513179 | 1777.0759503975294 | +| 0.1 | 1589.7116219510467 | 1179.72942803775 | 1352.0022254220246 | 1341.4338804409483 | +| 0.2 | 1142.997621862699 | 926.7582963947812 | 1024.1330983087387 | 1020.8867882079461 | +| 0.3 | 944.8617686957859 | 792.8011031462112 | 862.4832647298764 | 861.2504234307761 | +| 0.5 | 718.828994560167 | 620.903710128933 | 667.0056309724142 | 666.8566954899402 | +| 0.7 | 562.2951742741665 | 490.94452688226875 | 525.1451015371366 | 525.1396603301611 | +| 0.8 | 489.1190567170544 | 426.27565220132306 | 456.5371732569042 | 456.5895906525859 | +| 0.9 | 406.5315711877629 | 349.43698308548073 | 377.1985628605844 | 377.47132421036656 | +| 0.95 | 350.8298326892412 | 296.9223948614993 | 322.71122372134994 | 323.32706495268434 | +| 0.98 | 298.56036893769823 | 246.70008848738513 | 270.9421594385229 | 272.1107581062608 | +| 0.99 | 268.7286650340908 | 217.9437506795664 | 241.13875524919075 | 242.7587977692525 | ### Plots +There are also plenty of plots to explore our results with. Under the **Distribution Results** tab we have a frequency curve. -![Frequency curve (AEP versus quantile) for each alternative, with the credible band.](images/mixed-population-frequency.png) -*Figure: Frequency curve (AEP versus quantile) for each alternative, with the credible band.* - -![Posterior kernel density for each parameter.](images/mixed-population-kernel-density.png) -*Figure: Posterior kernel density for each parameter.* - -![Markov-chain traces for each parameter.](images/mixed-population-trace.png) -*Figure: Markov-chain traces for each parameter.* +![Frequency curve (AEP versus quantile) for each alternative, with the credible band.](../images/mixed-population-frequency.png) -![Autocorrelation function of the chains, used to estimate effective sample size.](images/mixed-population-autocorrelation.png) -*Figure: Autocorrelation function of the chains, used to estimate effective sample size.* - -### MCMC Diagnostics - -Verify chain convergence before interpreting any results: - -- **R-hat** — should be < 1.01 for every parameter. -- **Effective Sample Size (ESS)** — at least a few hundred per parameter. -- **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). -- **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. +*Figure: Frequency curve (AEP versus quantile), with the credible band.* ## Next Steps - Compare **competing-risks** (max of two CDFs) versus **AMS-mixture** (weighted CDFs) for combining sub-populations. -- Use the per-population sub-fits to inform engineering judgment about flood-type frequencies. - -## References - - - ---- - -_This tutorial was generated from the project's `.bestfit` file metadata. The narrative and figure / table sections are placeholders — capture screenshots from the BestFit GUI and paste output tables to complete the guide._ +- Use the per-population sub-fits to inform engineering judgment about flood-type frequencies. \ No newline at end of file diff --git a/examples/4-univariate-distribution-analysis/README.md b/examples/4-univariate-distribution-analysis/README.md index 3a49855..e4a440a 100644 --- a/examples/4-univariate-distribution-analysis/README.md +++ b/examples/4-univariate-distribution-analysis/README.md @@ -62,15 +62,6 @@ Before interpreting any result: The DEMCzs sampler is the default workhorse and converges reliably on routine LP-III, GEV, and Gumbel fits within 2,000-5,000 iterations after a 1,000-2,000 warmup. -## Screenshot Images - -Tutorial screenshot placeholders reference images in an `images/` subfolder under each example. To add screenshots: - -1. Create an `images/` folder in the example's directory. -2. Capture screenshots from RMC-BestFit matching the alt-text descriptions. -3. Save as PNG with the filename specified in each image reference. -4. Naming convention: `-.png` (e.g., `viglione-frequency.png`, `blakely-trace.png`). - ## Next Steps After univariate frequency analysis: diff --git a/examples/4-univariate-distribution-analysis/images/mixed-population-frequency.png b/examples/4-univariate-distribution-analysis/images/mixed-population-frequency.png new file mode 100644 index 0000000..d4d8aa0 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/images/mixed-population-frequency.png differ diff --git a/examples/4-univariate-distribution-analysis/images/mixture-autocorrelation-w1.png b/examples/4-univariate-distribution-analysis/images/mixture-autocorrelation-w1.png new file mode 100644 index 0000000..af658b8 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/images/mixture-autocorrelation-w1.png differ diff --git a/examples/4-univariate-distribution-analysis/images/mixture-frequency.png b/examples/4-univariate-distribution-analysis/images/mixture-frequency.png new file mode 100644 index 0000000..0daa3d7 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/images/mixture-frequency.png differ diff --git a/examples/4-univariate-distribution-analysis/images/mixture-kernel-density-w1.png b/examples/4-univariate-distribution-analysis/images/mixture-kernel-density-w1.png new file mode 100644 index 0000000..ba2a676 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/images/mixture-kernel-density-w1.png differ diff --git a/examples/4-univariate-distribution-analysis/images/mixture-trace-w1.png b/examples/4-univariate-distribution-analysis/images/mixture-trace-w1.png new file mode 100644 index 0000000..f04fb84 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/images/mixture-trace-w1.png differ diff --git a/examples/4-univariate-distribution-analysis/images/point-process-autocorrelation-location.png b/examples/4-univariate-distribution-analysis/images/point-process-autocorrelation-location.png new file mode 100644 index 0000000..5e2ef35 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/images/point-process-autocorrelation-location.png differ diff --git a/examples/4-univariate-distribution-analysis/images/point-process-frequency.png b/examples/4-univariate-distribution-analysis/images/point-process-frequency.png new file mode 100644 index 0000000..a09be1c Binary files /dev/null and b/examples/4-univariate-distribution-analysis/images/point-process-frequency.png differ diff --git a/examples/4-univariate-distribution-analysis/images/point-process-kernel-density-location.png b/examples/4-univariate-distribution-analysis/images/point-process-kernel-density-location.png new file mode 100644 index 0000000..ae593bd Binary files /dev/null and b/examples/4-univariate-distribution-analysis/images/point-process-kernel-density-location.png differ diff --git a/examples/4-univariate-distribution-analysis/images/point-process-trace-location.png b/examples/4-univariate-distribution-analysis/images/point-process-trace-location.png new file mode 100644 index 0000000..9cceb20 Binary files /dev/null and b/examples/4-univariate-distribution-analysis/images/point-process-trace-location.png differ diff --git a/examples/5-bivariate-distribution-analysis/1-bivariate-distributions/README.txt b/examples/5-bivariate-distribution-analysis/1-bivariate-distributions/README.txt deleted file mode 100644 index e33877b..0000000 --- a/examples/5-bivariate-distribution-analysis/1-bivariate-distributions/README.txt +++ /dev/null @@ -1,3 +0,0 @@ -Bivariate Distribution Examples: - -This example demonstrates fitting bivariate copulas for various copula types. Each dataset is synthetic, with marginal normal distributions and differing copula dependencies. \ No newline at end of file diff --git a/examples/5-bivariate-distribution-analysis/1-bivariate-distributions/bivariate-distribution-examples.bestfit b/examples/5-bivariate-distribution-analysis/1-bivariate-distributions/bivariate-distribution-examples.bestfit index b47408a..67b8635 100644 Binary files a/examples/5-bivariate-distribution-analysis/1-bivariate-distributions/bivariate-distribution-examples.bestfit and b/examples/5-bivariate-distribution-analysis/1-bivariate-distributions/bivariate-distribution-examples.bestfit differ diff --git a/examples/5-bivariate-distribution-analysis/1-bivariate-distributions/bivariate-distribution-examples.md b/examples/5-bivariate-distribution-analysis/1-bivariate-distributions/bivariate-distribution-examples.md index 521bb16..5eac4e8 100644 --- a/examples/5-bivariate-distribution-analysis/1-bivariate-distributions/bivariate-distribution-examples.md +++ b/examples/5-bivariate-distribution-analysis/1-bivariate-distributions/bivariate-distribution-examples.md @@ -61,18 +61,17 @@ Bivariate distribution fitting using six copula families (AMH, Clayton, Frank, G ### Exploring the Elements -For each Bivariate Distribution alternative: +For each Bivariate Distribution analysis: -1. Click the alternative in the Project Explorer. -2. Open the **Joint Density** tab to see the fitted copula contour overlay on the data scatter. -3. Inspect the dependence parameter (theta or rho) in the parameter table. -4. Compare AIC / BIC across copula families to select the best fit. +1. Click the analysis in the Project Explorer. +2. Open the **Distribution Results** tab to see the fitted copula contour overlay on the data scatter. +3. Inspect the dependence parameter (θ) in the parameter table. +4. Compare AIC / BIC across copula families to select the best fit. The copula method can be changed from the Method dropdown in the **Properties** panel. ## Analysis Settings -Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any alternative to inspect: +Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any Bivariate Distribution analysis to inspect: -- **Sampler type** (DEMCzs, ARWMH, HMC). - **Iterations / Warm-up Iterations** — total post-warmup samples per chain. - **Number of Chains** — typically 6 for routine work. - **Thinning Interval** — keeps every Nth sample to reduce storage / autocorrelation. @@ -80,65 +79,49 @@ Each Bayesian analysis in this project uses the DEMCzs sampler with project-spec - **Credible Interval Width** — typically 0.90 or 0.95. ## Expected Results - - +Below are the expected results for Bivaraite Distribution Analysis labeled "AMH Copula"; this should be the first analysis in the list. +Be sure to explore all of the analyses provided! ### Parameter Estimates +The parameter estimates are found under the **MCMC Report** tab to the left as parameter summary statistics. - - -| Alternative | Parameter | Mean | Median | Lower CI | Upper CI | R-hat | ESS | +| Parameter | Mean | Std Dev | 5% | Median | 95% |R-hat | ESS | |---|---|---|---|---|---|---|---| -| _(placeholder)_ | | | | | | | | +| Dependency (θ) | 0.814271 | 0.127172 | 0.572653 | 0.84314 | 0.960294 | 1.0001 | 7748 | + +### Plots +There are plenty of plots to explore in the Bivariate Distribution Analysis. Under **Distribution Results** is simulated data from the joint copula denisty overliad on the X-Y data. -### Frequency / Quantile Table +![Joint copula density contour overlaid on the X-Y scatter.](../images/bivariate-joint-density.png) - +*Figure 1: Joint copula density contour overlaid on the X-Y scatter.* -| AEP (%) | Return Period (yr) | Median | Lower CI | Upper CI | -|---|---|---|---|---| -| 50 | 2 | | | | -| 10 | 10 | | | | -| 1 | 100 | | | | -| 0.5 | 200 | | | | -| 0.2 | 500 | | | | +The **Kernal Density** tab shows an estimate for the pdf of a parameter. -### Plots +![Kernel density of dependency (θ).](../images/bivariate-kernal-density.png) + +*Figure 2: Kernel density of dependency (θ).* -![Joint copula density contour overlaid on the X-Y scatter.](images/bivariate-joint-density.png) -*Figure: Joint copula density contour overlaid on the X-Y scatter.* +The **Markov Chain Traces** tab explores the traces of each Markov chain as it explores the posterior space in order to converge to a parameter. -![Marginal X frequency curve.](images/bivariate-marginal-x.png) -*Figure: Marginal X frequency curve.* +![Markov chain trace of dependency (θ).](../images/bivariate-trace.png) -![Marginal Y frequency curve.](images/bivariate-marginal-y.png) -*Figure: Marginal Y frequency curve.* +*Figure 3: Markov chain trace of dependency (θ).* -![Derived coincident-response frequency curve (CFA only).](images/bivariate-frequency.png) -*Figure: Derived coincident-response frequency curve (CFA only).* ### MCMC Diagnostics -Verify chain convergence before interpreting any results: +One should always verify chain convergence before interpreting any results. There are a variety of ways including: - **R-hat** — should be < 1.01 for every parameter. - **Effective Sample Size (ESS)** — at least a few hundred per parameter. - **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). - **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. +These can be found under the **Markov Chain Traces** and **MCMC Reports** tabs. + ## Next Steps - Use the joint distribution to estimate **AND / OR / Kendall-return-period** quantiles. - Compare copula families via AIC / BIC; the heavy-tail families (Gumbel, Joe) often win for hydrologic peaks. -- Pair with a **Coincident Frequency Analysis** to derive a sum / difference / max distribution. - -## References - - - ---- - -_This tutorial was generated from the project's `.bestfit` file metadata. The narrative and figure / table sections are placeholders — capture screenshots from the BestFit GUI and paste output tables to complete the guide._ +- Pair with a **Coincident Frequency Analysis** to derive a sum / difference / max distribution. \ No newline at end of file diff --git a/examples/5-bivariate-distribution-analysis/2-coincident-frequency/sum-two-normals.bestfit b/examples/5-bivariate-distribution-analysis/2-coincident-frequency/sum-two-normals.bestfit index c28a4b4..7a10998 100644 Binary files a/examples/5-bivariate-distribution-analysis/2-coincident-frequency/sum-two-normals.bestfit and b/examples/5-bivariate-distribution-analysis/2-coincident-frequency/sum-two-normals.bestfit differ diff --git a/examples/5-bivariate-distribution-analysis/2-coincident-frequency/sum-two-normals.md b/examples/5-bivariate-distribution-analysis/2-coincident-frequency/sum-two-normals.md index e4ddab3..8153881 100644 --- a/examples/5-bivariate-distribution-analysis/2-coincident-frequency/sum-two-normals.md +++ b/examples/5-bivariate-distribution-analysis/2-coincident-frequency/sum-two-normals.md @@ -57,18 +57,16 @@ Coincident frequency analysis (CFA) verification using the sum of two correlated ### Exploring the Elements -For each Coincident Frequency Analysis alternative: +For each Coincident Frequency Analysis: -1. Click the alternative in the Project Explorer. -2. Open the **Joint Density** tab to view the bivariate fit. -3. Open the **Frequency** tab to view the derived response-variable AEP curve. -4. Adjust the **X / Y ordinates** in the Properties panel to refine the response surface. +1. Click the analysis in the Project Explorer. +2. Open the **Frequency Plot** tab at the top to view the derived response-variable AEP curve. +3. Adjust the **X / Y ordinates** in the Properties panel to refine the response surface. ## Analysis Settings -Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any alternative to inspect: +Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any Bivariate Distribution Analysis (NOT the Coincident Frequency Analysis element) to inspect: -- **Sampler type** (DEMCzs, ARWMH, HMC). - **Iterations / Warm-up Iterations** — total post-warmup samples per chain. - **Number of Chains** — typically 6 for routine work. - **Thinning Interval** — keeps every Nth sample to reduce storage / autocorrelation. @@ -76,64 +74,61 @@ Each Bayesian analysis in this project uses the DEMCzs sampler with project-spec - **Credible Interval Width** — typically 0.90 or 0.95. ## Expected Results - - - -### Parameter Estimates - - - -| Alternative | Parameter | Mean | Median | Lower CI | Upper CI | R-hat | ESS | -|---|---|---|---|---|---|---|---| -| _(placeholder)_ | | | | | | | | +Below are the expected results for Coincident Frequency Analysis labeled "CFA - Rho = 0/0"; this should be the first CFA in the list. +Be sure to explore all of the analyses provided! ### Frequency / Quantile Table +Select the **Tabular Results** tab at the top to see the frequency plot's value at each return level probability. - - -| AEP (%) | Return Period (yr) | Median | Lower CI | Upper CI | +| Response Value | 97.5% CI | 2.5% CI | Posterior Predictive | Posterior Mean | |---|---|---|---|---| -| 50 | 2 | | | | -| 10 | 10 | | | | -| 1 | 100 | | | | -| 0.5 | 200 | | | | -| 0.2 | 500 | | | | +| 87 | 0.9999575164826484 | 0.9986818487735876 | 0.999613995636363 | 0.9996934913620849 | +| 96.78947368421052 | 0.9996787406955139 | 0.9952157677102006 | 0.9982686516147767 | 0.9984855324680553 | +| 106.57894736842105 | 0.998366757951269 | 0.9860986620898814 | 0.994043386684129 | 0.9944813911685078 | +| 116.36842105263158 | 0.9939550615286463 | 0.9676112368720589 | 0.9837406725518051 | 0.9844151226179727 | +| 126.15789473684211 | 0.9828923754505756 | 0.9362476453725623 | 0.9635531943756771 | 0.964400332661703 | +| 135.94736842105263 | 0.9611124039143327 | 0.8906757145159339 | 0.9304756574653961 | 0.9313730567425466 | +| 145.73684210526315 | 0.9241556517523287 | 0.8283796634903918 | 0.8811213175678487 | 0.8818441882346706 | +| 155.5263157894737 | 0.8643601366355986 | 0.7445962955334277 | 0.8085886653308365 | 0.8090326043542164 | +| 165.31578947368422 | 0.7737423169912419 | 0.6358350551505616 | 0.7076660199675067 | 0.7079204843246665 | +| 175.10526315789474 | 0.6565437404710043 | 0.5081224804755793 | 0.5835296155575668 | 0.5836123596998999 | +| 184.89473684210526 | 0.525089963663616 | 0.37584797803875436 | 0.4496218873383308 | 0.4495368249067684 | +| 194.68421052631578 | 0.39445447945846746 | 0.25387100652883515 | 0.32176132362284177 | 0.32153482475909334 | +| 204.4736842105263 | 0.280416509051367 | 0.15614761940576735 | 0.21464997198347982 | 0.21427673016789273 | +| 214.26315789473682 | 0.19052389556551255 | 0.08926616637168196 | 0.1356419024545678 | 0.1350025330429513 | +| 224.05263157894737 | 0.1234644119804129 | 0.04707315167289306 | 0.08089664285995847 | 0.08004867303350849 | +| 233.8421052631579 | 0.07337327012781823 | 0.021469575628803795 | 0.04347994191646845 | 0.04264350481368828 | +| 243.6315789473684 | 0.03818934071234933 | 0.00794936677105736 | 0.019974200826754922 | 0.01927516685952424 | +| 253.42105263157893 | 0.01689613766156331 | 0.0022476626007764794 | 0.007558749480297321 | 0.00707633362796023 | +| 263.2105263157895 | 0.006082820643538663 | 0.0004665446086391608 | 0.0022762189355344316 | 0.002021765011468002 | +| 273 | 0.0017213102993187649 | 6.475197382132259E-05 | 0.0005270202407436539 | 0.0004277727678921872 ### Plots +There are plenty of plots to explore in the Coincident Frequency Anaylsis. First we can look at the Bivariate Distribution Analysis used to build the Coincident Frequency Anaylsis. +Select the Bivarate Distribution Analysis labeled "Normal Copula - Rho = 0.0". From there, under **Distribution Results** is simulated data from the joint copula denisty overliad on the X-Y data. + +![Joint copula density contour overlaid on the X-Y scatter.](../images/sum-two-normals-joint-density.png) -![Joint copula density contour overlaid on the X-Y scatter.](images/sum-two-normals-joint-density.png) -*Figure: Joint copula density contour overlaid on the X-Y scatter.* +*Figure 1: Joint copula density contour overlaid on the X-Y scatter.* -![Marginal X frequency curve.](images/sum-two-normals-marginal-x.png) -*Figure: Marginal X frequency curve.* +Going back to the Coincident Frequency Analysis, there is the frequency plot of annual exccedance probabilities. -![Marginal Y frequency curve.](images/sum-two-normals-marginal-y.png) -*Figure: Marginal Y frequency curve.* +![Derived coincident-response frequency curve.](../images/sum-two-normals-frequency.png) -![Derived coincident-response frequency curve (CFA only).](images/sum-two-normals-frequency.png) -*Figure: Derived coincident-response frequency curve (CFA only).* +*Figure 2: Derived coincident-response frequency curve.* ### MCMC Diagnostics -Verify chain convergence before interpreting any results: +One should always verify chain convergence before interpreting any results. There are a variety of ways including: - **R-hat** — should be < 1.01 for every parameter. - **Effective Sample Size (ESS)** — at least a few hundred per parameter. - **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). - **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. +These can be found under the **Markov Chain Traces** and **MCMC Reports** tabs of the Bivariate Distribution Analysis (NOT the Coincident Frequency Analysis element). + ## Next Steps - Use the joint AEP table to size structures whose response depends on two correlated drivers (e.g., coincident streamflow and downstream stage). -- Compare results against a closed-form analytical answer where one is available. - -## References - - - ---- - -_This tutorial was generated from the project's `.bestfit` file metadata. The narrative and figure / table sections are placeholders — capture screenshots from the BestFit GUI and paste output tables to complete the guide._ +- Compare results against a closed-form analytical answer where one is available. \ No newline at end of file diff --git a/examples/5-bivariate-distribution-analysis/2-coincident-frequency/waimea-river-stage-frequency.bestfit b/examples/5-bivariate-distribution-analysis/2-coincident-frequency/waimea-river-stage-frequency.bestfit index 89036ff..a4242de 100644 Binary files a/examples/5-bivariate-distribution-analysis/2-coincident-frequency/waimea-river-stage-frequency.bestfit and b/examples/5-bivariate-distribution-analysis/2-coincident-frequency/waimea-river-stage-frequency.bestfit differ diff --git a/examples/5-bivariate-distribution-analysis/2-coincident-frequency/waimea-river-stage-frequency.md b/examples/5-bivariate-distribution-analysis/2-coincident-frequency/waimea-river-stage-frequency.md index 0b7736d..da94d7d 100644 --- a/examples/5-bivariate-distribution-analysis/2-coincident-frequency/waimea-river-stage-frequency.md +++ b/examples/5-bivariate-distribution-analysis/2-coincident-frequency/waimea-river-stage-frequency.md @@ -75,19 +75,16 @@ Coincident peak-flow analysis for the Waimea River and Makaweli River, Kauai, Ha 3. Open `waimea-river-stage-frequency.bestfit`. ### Exploring the Elements +For each Coincident Frequency Analysis: -For each Coincident Frequency Analysis alternative: - -1. Click the alternative in the Project Explorer. -2. Open the **Joint Density** tab to view the bivariate fit. -3. Open the **Frequency** tab to view the derived response-variable AEP curve. -4. Adjust the **X / Y ordinates** in the Properties panel to refine the response surface. +1. Click the analysis in the Project Explorer. +2. Open the **Frequency Plot** tab at the top to view the derived response-variable AEP curve. +3. Adjust the **X / Y ordinates** in the Properties panel to refine the response surface. ## Analysis Settings -Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any alternative to inspect: +Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any Bivariate Distribution Analysis (NOT the Coincident Frequency Analysis element) to inspect: -- **Sampler type** (DEMCzs, ARWMH, HMC). - **Iterations / Warm-up Iterations** — total post-warmup samples per chain. - **Number of Chains** — typically 6 for routine work. - **Thinning Interval** — keeps every Nth sample to reduce storage / autocorrelation. @@ -95,64 +92,91 @@ Each Bayesian analysis in this project uses the DEMCzs sampler with project-spec - **Credible Interval Width** — typically 0.90 or 0.95. ## Expected Results - - - -### Parameter Estimates - - - -| Alternative | Parameter | Mean | Median | Lower CI | Upper CI | R-hat | ESS | -|---|---|---|---|---|---|---|---| -| _(placeholder)_ | | | | | | | | +Below are the expected results for Coincident Frequency Analysis labeled "CFA - Normal - Conditional"; this should be the only CFA in the list. +Be sure to explore all of the analyses provided! ### Frequency / Quantile Table +Select the **Tabular Results** tab at the top to see the frequency plot's value at each return level probability. - - -| AEP (%) | Return Period (yr) | Median | Lower CI | Upper CI | +| Response Value | 97.5% CI | 2.5% CI | Posterior Predictive | Posterior Mean | |---|---|---|---|---| -| 50 | 2 | | | | -| 10 | 10 | | | | -| 1 | 100 | | | | -| 0.5 | 200 | | | | -| 0.2 | 500 | | | | +| 7.14 | 0.999598853349256 | 0.9822736153183459 | 0.9939375860433544 | 0.9949507109374724 | +| 7.568775510204081 | 0.998992633505899 | 0.9751139659037453 | 0.9907136406885692 | 0.991713014185094 | +| 7.997551020408163 | 0.9976976594194389 | 0.9657107403795586 | 0.9859701486370981 | 0.9868155773145066 | +| 8.426326530612245 | 0.9951399769214387 | 0.9535796232730303 | 0.9791221668692526 | 0.9796567296997515 | +| 8.855102040816327 | 0.9904203859035741 | 0.9381901227534936 | 0.9694422936550987 | 0.9695425576935874 | +| 9.283877551020408 | 0.9825974772449797 | 0.9193613702569976 | 0.9560742613165246 | 0.95572590988006 | +| 9.71265306122449 | 0.9709379340863057 | 0.896072407078915 | 0.9387025860669641 | 0.9380434651962304 | +| 10.141428571428571 | 0.9590321362549451 | 0.8736553675865412 | 0.9214522379480089 | 0.9203697134040612 | +| 10.570204081632653 | 0.9434842855528288 | 0.8475568979008056 | 0.9003846421165421 | 0.8989656628009409 | +| 10.998979591836735 | 0.9257811833836075 | 0.8198583614785113 | 0.8769782160857079 | 0.875143645278772 | +| 11.427755102040816 | 0.902779848570538 | 0.7866596190760782 | 0.8485968144731343 | 0.8462781115411291 | +| 11.856530612244898 | 0.87329254874581 | 0.7476759718018776 | 0.8140108343560754 | 0.81133967585813 | +| 12.28530612244898 | 0.8435633851807174 | 0.7101600843275624 | 0.7795891376739831 | 0.7767387509457312 | +| 12.71408163265306 | 0.8109673052969281 | 0.6692210788980608 | 0.7420207987900213 | 0.7391275866926545 | +| 13.142857142857142 | 0.7751233461090515 | 0.6257236765307417 | 0.7017537398355265 | 0.6989679882428308 | +| 13.571632653061224 | 0.735492222790967 | 0.5800419687989538 | 0.6583967275836747 | 0.6560351878865632 | +| 14.000408163265305 | 0.6867740374439698 | 0.5274612527039573 | 0.6068498245211181 | 0.6047089906043757 | +| 14.429183673469387 | 0.6426544666024442 | 0.4811312903252858 | 0.5610771938950695 | 0.5591831796954536 | +| 14.857959183673469 | 0.5971552730053807 | 0.43498382774138133 | 0.5147994661168663 | 0.5131978859597698 | +| 15.286734693877552 | 0.551391048200534 | 0.3909212623915677 | 0.46901828233088655 | 0.46773858675813307 | +| 15.715510204081632 | 0.505439810166183 | 0.34845544105148096 | 0.42449848666695345 | 0.42356489972882405 | +| 16.144285714285715 | 0.46026868202171217 | 0.3070522085346464 | 0.38064430888923545 | 0.38009572261449287 | +| 16.573061224489795 | 0.41933517837328554 | 0.27131477471237936 | 0.34227383009442636 | 0.34203011924043003 | +| 17.001836734693878 | 0.37318005689947487 | 0.2326905156308874 | 0.2998219939577745 | 0.30026468086384983 | +| 17.430612244897958 | 0.32252516977836154 | 0.1914503132754313 | 0.25385910192505645 | 0.2543238333756812 | +| 17.85938775510204 | 0.2705946189260725 | 0.15067212169511615 | 0.2077453166949087 | 0.20802436530468937 | +| 18.28816326530612 | 0.2345279059175711 | 0.12327148189975427 | 0.17563114927017315 | 0.17582924074636608 | +| 18.716938775510204 | 0.20100407285146754 | 0.09929447154133551 | 0.1467503362965446 | 0.14693243477858042 | +| 19.145714285714284 | 0.17069807087558242 | 0.07872028292859645 | 0.12134021905793459 | 0.12157385883802818 | +| 19.574489795918367 | 0.1439854205742417 | 0.061233131882399476 | 0.09932106799716632 | 0.09958910351514627 | +| 20.003265306122447 | 0.12042920458589632 | 0.04653494988115461 | 0.08021986440578467 | 0.08051029493294004 | +| 20.43204081632653 | 0.09953035404179641 | 0.03431744920465619 | 0.06410122007471096 | 0.06453708865415941 | +| 20.86081632653061 | 0.08214263614833486 | 0.024500735151532067 | 0.05064725553014899 | 0.05111664185573794 | +| 21.289591836734694 | 0.06789162681024165 | 0.017113089788251955 | 0.039820708785729686 | 0.04018467099185663 | +| 21.718367346938773 | 0.05650618275141569 | 0.011486515489130027 | 0.0312771621351342 | 0.031574367127246816 | +| 22.147142857142857 | 0.046904206146289304 | 0.0075260480203095505 | 0.024417822873657305 | 0.024509291723632698 | +| 22.575918367346937 | 0.03889686001599997 | 0.004364347222958325 | 0.018793757515630137 | 0.018743819716992904 | +| 23.00469387755102 | 0.03193163825599845 | 0.0023228065036558997 | 0.014344744422216317 | 0.01410773728214565 | +| 23.433469387755103 | 0.025946457232817917 | 0.001113250553042527 | 0.010836136315275236 | 0.010387970821016057 | +| 23.862244897959183 | 0.020997540204862483 | 0.00048595348833170267 | 0.008074600093777844 | 0.0074378003609448795 | +| 24.291020408163266 | 0.016000951438390424 | 0.00016883947013147097 | 0.005594465622026487 | 0.004815627761223018 | +| 24.719795918367346 | 0.011469923775680976 | 1.4352487131663592E-05 | 0.0035521474318838636 | 0.002709894132966517 | +| 25.14857142857143 | 0.007855081717688683 | 3.060522803910437E-07 | 0.0021418800818126115 | 0.00133683155531783 | +| 25.57734693877551 | 0.005303396990455819 | 1.8900372877883585E-09 | 0.0012842802746611385 | 0.0006006781759374524 | +| 26.006122448979593 | 0.0034348850259895147 | 4.801670172582805E-12 | 0.0007579949381398096 | 0.000240586158519851 | +| 26.434897959183672 | 0.0021855603877346066 | 9.999778782798785E-13 | 0.0004468675964164098 | 8.327427542775823E-05 | +| 26.863673469387756 | 0.001397674916349322 | 9.999778782798785E-13 | 0.00027014002631956663 | 2.54311831492382E-05 | +| 27.292448979591835 | 0.00089938612296066 | 9.999778782798785E-13 | 0.0001674949155049129 | 7.176272680764484E-06 | +| 27.72122448979592 | 0.0005587444810815852 | 9.999778782798785E-13 | 0.00010473493976947116 | 1.866355555546484E-06 | +| 28.15 | 0.0003469296766613005 | 9.999778782798785E-13 | 6.588241335717548E-05 | 4.4700050161328164E-07 | ### Plots +There are plenty of plots to explore in the Coincident Frequency Anaylsis. First we can look at the Bivariate Distribution Analysis used to build the Coincident Frequency Anaylsis. +Select the Bivarate Distribution Analysis labeled "Normal Copula - Conditional". From there, under **Distribution Results** is simulated data from the joint copula denisty overliad on the X-Y data. + +![Joint copula density contour overlaid on the X-Y scatter.](../images/waimea-joint-density.png) -![Joint copula density contour overlaid on the X-Y scatter.](images/waimea-joint-density.png) -*Figure: Joint copula density contour overlaid on the X-Y scatter.* +*Figure 1: Joint copula density contour overlaid on the X-Y scatter.* -![Marginal X frequency curve.](images/waimea-marginal-x.png) -*Figure: Marginal X frequency curve.* +Going back to the Coincident Frequency Analysis, there is the frequency plot of annual exccedance probabilities. -![Marginal Y frequency curve.](images/waimea-marginal-y.png) -*Figure: Marginal Y frequency curve.* +![Derived coincident-response frequency curve.](../images/waimea-frequency.png) -![Derived coincident-response frequency curve (CFA only).](images/waimea-frequency.png) -*Figure: Derived coincident-response frequency curve (CFA only).* +*Figure 2: Derived coincident-response frequency curve.* ### MCMC Diagnostics -Verify chain convergence before interpreting any results: +One should always verify chain convergence before interpreting any results. There are a variety of ways including: - **R-hat** — should be < 1.01 for every parameter. - **Effective Sample Size (ESS)** — at least a few hundred per parameter. - **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). - **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. +These can be found under the **Markov Chain Traces** and **MCMC Reports** tabs of the Bivariate Distribution Analysis (NOT the Coincident Frequency Analysis element). + ## Next Steps - Use the joint AEP table to size structures whose response depends on two correlated drivers (e.g., coincident streamflow and downstream stage). -- Compare results against a closed-form analytical answer where one is available. - -## References - - - ---- - -_This tutorial was generated from the project's `.bestfit` file metadata. The narrative and figure / table sections are placeholders — capture screenshots from the BestFit GUI and paste output tables to complete the guide._ +- Compare results against a closed-form analytical answer where one is available. \ No newline at end of file diff --git a/examples/5-bivariate-distribution-analysis/README.md b/examples/5-bivariate-distribution-analysis/README.md index 3649e68..91c5f45 100644 --- a/examples/5-bivariate-distribution-analysis/README.md +++ b/examples/5-bivariate-distribution-analysis/README.md @@ -59,10 +59,6 @@ Each Bivariate Distribution Analysis element references two existing Univariate Compare candidates by AIC / BIC; Gumbel and Frank are the typical winners for hydrologic peaks. -## Screenshot Images - -Capture screenshots into `images/` subfolders next to each example. Naming convention: `-.png` (e.g., `waimea-joint-density.png`, `sum-two-normals-marginal-x.png`). - ## Next Steps After bivariate / CFA analysis: diff --git a/examples/5-bivariate-distribution-analysis/images/bivariate-joint-density.png b/examples/5-bivariate-distribution-analysis/images/bivariate-joint-density.png new file mode 100644 index 0000000..59c5ceb Binary files /dev/null and b/examples/5-bivariate-distribution-analysis/images/bivariate-joint-density.png differ diff --git a/examples/5-bivariate-distribution-analysis/images/bivariate-kernal-density.png b/examples/5-bivariate-distribution-analysis/images/bivariate-kernal-density.png new file mode 100644 index 0000000..704672e Binary files /dev/null and b/examples/5-bivariate-distribution-analysis/images/bivariate-kernal-density.png differ diff --git a/examples/5-bivariate-distribution-analysis/images/bivariate-trace.png b/examples/5-bivariate-distribution-analysis/images/bivariate-trace.png new file mode 100644 index 0000000..57d6c5a Binary files /dev/null and b/examples/5-bivariate-distribution-analysis/images/bivariate-trace.png differ diff --git a/examples/5-bivariate-distribution-analysis/images/sum-two-normals-frequency.png b/examples/5-bivariate-distribution-analysis/images/sum-two-normals-frequency.png new file mode 100644 index 0000000..e50d5ea Binary files /dev/null and b/examples/5-bivariate-distribution-analysis/images/sum-two-normals-frequency.png differ diff --git a/examples/5-bivariate-distribution-analysis/images/sum-two-normals-joint-density.png b/examples/5-bivariate-distribution-analysis/images/sum-two-normals-joint-density.png new file mode 100644 index 0000000..15fadd8 Binary files /dev/null and b/examples/5-bivariate-distribution-analysis/images/sum-two-normals-joint-density.png differ diff --git a/examples/5-bivariate-distribution-analysis/images/waimea-frequency.png b/examples/5-bivariate-distribution-analysis/images/waimea-frequency.png new file mode 100644 index 0000000..5ed25b0 Binary files /dev/null and b/examples/5-bivariate-distribution-analysis/images/waimea-frequency.png differ diff --git a/examples/5-bivariate-distribution-analysis/images/waimea-joint-density.png b/examples/5-bivariate-distribution-analysis/images/waimea-joint-density.png new file mode 100644 index 0000000..62f4e4d Binary files /dev/null and b/examples/5-bivariate-distribution-analysis/images/waimea-joint-density.png differ diff --git a/examples/6-rating-curve-analysis/README.md b/examples/6-rating-curve-analysis/README.md index 6759f0a..da7ffdc 100644 --- a/examples/6-rating-curve-analysis/README.md +++ b/examples/6-rating-curve-analysis/README.md @@ -49,10 +49,6 @@ A fitted rating curve produces: - **Posterior predictive bands** at user-selected stage ordinates (controlled via `MinStage`, `MaxStage`, `StageBins` in the Properties panel). - **Application output**: feeding a stage Time Series Data element through the fitted rating curve produces a discharge time series with credible bands. -## Screenshot Images - -Capture screenshots into an `images/` subfolder next to each example. Naming convention: `-.png` (e.g., `susquehanna-rating-curve.png`, `synthetic-rc-residuals.png`). - ## Next Steps After fitting a rating curve: diff --git a/examples/6-rating-curve-analysis/README.txt b/examples/6-rating-curve-analysis/README.txt deleted file mode 100644 index be8522b..0000000 --- a/examples/6-rating-curve-analysis/README.txt +++ /dev/null @@ -1,3 +0,0 @@ -Rating Curve Examples: - -This project demonstrates fitting rating curves to both synthetic and real-world datasets. A synthetic dataset is generated with known rating curve parameters, and 1-, 2-, and 3-segment rating curves are fit to recover the original relationships. BestFit is able to accurately recover the true parameters for each case. Additional examples include fitting a 1-segment rating curve to data from the Mississippi River at New Madrid and the Middle Fork Willamette River. These examples demonstrate the flexibility of BestFit’s rating curve fitting capabilities across simple and complex flow-stage relationships. \ No newline at end of file diff --git a/examples/6-rating-curve-analysis/USGS 14145000 MF Willamette River.bestfit.bak b/examples/6-rating-curve-analysis/USGS 14145000 MF Willamette River.bestfit.bak deleted file mode 100644 index 8cdfe09..0000000 Binary files a/examples/6-rating-curve-analysis/USGS 14145000 MF Willamette River.bestfit.bak and /dev/null differ diff --git a/examples/6-rating-curve-analysis/images/mississippi-rating-curve.png b/examples/6-rating-curve-analysis/images/mississippi-rating-curve.png new file mode 100644 index 0000000..bbf9ab5 Binary files /dev/null and b/examples/6-rating-curve-analysis/images/mississippi-rating-curve.png differ diff --git a/examples/6-rating-curve-analysis/images/mississippi-residuals.png b/examples/6-rating-curve-analysis/images/mississippi-residuals.png new file mode 100644 index 0000000..29d2013 Binary files /dev/null and b/examples/6-rating-curve-analysis/images/mississippi-residuals.png differ diff --git a/examples/6-rating-curve-analysis/images/mississippi-trace-h1.png b/examples/6-rating-curve-analysis/images/mississippi-trace-h1.png new file mode 100644 index 0000000..45af803 Binary files /dev/null and b/examples/6-rating-curve-analysis/images/mississippi-trace-h1.png differ diff --git a/examples/6-rating-curve-analysis/images/susquehanna-rating-curve.png b/examples/6-rating-curve-analysis/images/susquehanna-rating-curve.png new file mode 100644 index 0000000..59ddd98 Binary files /dev/null and b/examples/6-rating-curve-analysis/images/susquehanna-rating-curve.png differ diff --git a/examples/6-rating-curve-analysis/images/susquehanna-residuals.png b/examples/6-rating-curve-analysis/images/susquehanna-residuals.png new file mode 100644 index 0000000..8babab2 Binary files /dev/null and b/examples/6-rating-curve-analysis/images/susquehanna-residuals.png differ diff --git a/examples/6-rating-curve-analysis/images/susquehanna-trace-h1.png b/examples/6-rating-curve-analysis/images/susquehanna-trace-h1.png new file mode 100644 index 0000000..39f2c1f Binary files /dev/null and b/examples/6-rating-curve-analysis/images/susquehanna-trace-h1.png differ diff --git a/examples/6-rating-curve-analysis/images/synthetic-rc-rating-curve.png b/examples/6-rating-curve-analysis/images/synthetic-rc-rating-curve.png new file mode 100644 index 0000000..76437fb Binary files /dev/null and b/examples/6-rating-curve-analysis/images/synthetic-rc-rating-curve.png differ diff --git a/examples/6-rating-curve-analysis/images/synthetic-rc-residuals.png b/examples/6-rating-curve-analysis/images/synthetic-rc-residuals.png new file mode 100644 index 0000000..ce4c351 Binary files /dev/null and b/examples/6-rating-curve-analysis/images/synthetic-rc-residuals.png differ diff --git a/examples/6-rating-curve-analysis/images/synthetic-rc-trace-h1.png b/examples/6-rating-curve-analysis/images/synthetic-rc-trace-h1.png new file mode 100644 index 0000000..fcd7a04 Binary files /dev/null and b/examples/6-rating-curve-analysis/images/synthetic-rc-trace-h1.png differ diff --git a/examples/6-rating-curve-analysis/synthetic-rating-curve-examples.bestfit b/examples/6-rating-curve-analysis/synthetic-rating-curve-examples.bestfit index b388713..95ea3a5 100644 Binary files a/examples/6-rating-curve-analysis/synthetic-rating-curve-examples.bestfit and b/examples/6-rating-curve-analysis/synthetic-rating-curve-examples.bestfit differ diff --git a/examples/6-rating-curve-analysis/synthetic-rating-curve-examples.md b/examples/6-rating-curve-analysis/synthetic-rating-curve-examples.md index 4f00fb8..f9cd38c 100644 --- a/examples/6-rating-curve-analysis/synthetic-rating-curve-examples.md +++ b/examples/6-rating-curve-analysis/synthetic-rating-curve-examples.md @@ -33,18 +33,17 @@ Synthetic stage-discharge rating curve fits using one-, two-, and three-segment ### Exploring the Elements -For each Rating Curve Analysis alternative: +For each Rating Curve Analysis: -1. Click the alternative in the Project Explorer. -2. Open the **Rating Curve** tab to view the fit overlaid on the measured stage / discharge pairs. -3. Adjust **MinStage**, **MaxStage**, and **StageBins** in the Properties panel to set the prediction range. -4. Inspect breakpoints (h2, h3) for multi-segment fits. +1. Click the analysis in the Project Explorer. +2. Open the **Rating Curve Results** tab to the left to view the fit overlaid on the measured stage / discharge pairs. +3. Adjust **MinStage**, **MaxStage**, and **StageBins** in the **Properties** panel under **Output** to set the prediction range. +4. Inspect breakpoints (h2, h3) behavior for multi-segment fits. ## Analysis Settings -Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any alternative to inspect: +Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any Rating Curve Analysis to inspect: -- **Sampler type** (DEMCzs, ARWMH, HMC). - **Iterations / Warm-up Iterations** — total post-warmup samples per chain. - **Number of Chains** — typically 6 for routine work. - **Thinning Interval** — keeps every Nth sample to reduce storage / autocorrelation. @@ -53,61 +52,90 @@ Each Bayesian analysis in this project uses the DEMCzs sampler with project-spec ## Expected Results - +Below are the expected results for Rating Curve Analysis labeled "1 Segment Rating Curve"; this should be the first analysis in the list. +Be sure to explore all of the analyses provided! ### Parameter Estimates +The parameter estimates are found under the **MCMC Report** tab to the left as parameter summary statistics. - - -| Alternative | Parameter | Mean | Median | Lower CI | Upper CI | R-hat | ESS | +| Parameter | Mean | Std Dev | 5% | Median | 95% |R-hat | ESS | |---|---|---|---|---|---|---|---| -| _(placeholder)_ | | | | | | | | +| Zero-Flow Stage (h₁) | 0.986588 | 0.00618086 | 0.976184 | 0.986718 | 0.996666 | 1.0003 | 9570 | +| Coefficient (α₁) | 0.220643 | 0.0122755 | 0.200534 | 0.220647 | 0.240935 | 0.9998 | 9427 | +| Exponent (β₁) | 2.69251 | 0.0119837 | 2.67274 | 2.69241 | 2.71208 | 0.9998 | 9396 | +| Scale (σ) | 0.0510602 | 0.00211105 | 0.0477149 | 0.0509902 | 0.0546349 | 0.9999 | 9581 | ### Frequency / Quantile Table +While in the **Rating Curve Results** tab to the left, select Tabular Results to see the fitted curve values. Below are the first 30 rows of the table. - - -| AEP (%) | Return Period (yr) | Median | Lower CI | Upper CI | +| Stage | 95.0% CI | 5.0% CI | Posterior Predictive | Posterior Mean | |---|---|---|---|---| -| 50 | 2 | | | | -| 10 | 10 | | | | -| 1 | 100 | | | | -| 0.5 | 200 | | | | -| 0.2 | 500 | | | | +| -0.7326817927 | 0 | 0 | 0 | 0 | +| -0.5053910586757575 | 0 | 0 | 0 | 0 | +| -0.2781003246515151 | 0 | 0 | 0 | 0 | +| -0.05080959062727264 | 0 | 0 | 0 | 0 | +| 0.1764811433969698 | 0 | 0 | 0 | 0 | +| 0.40377187742121223 | 0 | 0 | 0 | 0 | +| 0.6310626114454547 | 0 | 0 | 0 | 0 | +| 0.8583533454696972 | 0 | 0 | 0 | 0 | +| 1.0856440794939397 | 0.004373040596761412 | 0.0024502071394302714 | 0.0033181357135632474 | 0.003288796086243071 | +| 1.3129348135181822 | 0.09953251883342444 | 0.06676688004068045 | 0.08194946486631781 | 0.08151122081152615 | +| 1.5402255475424247 | 0.41258379667686623 | 0.2787909602693334 | 0.34009199751969216 | 0.3382779019238859 | +| 1.7675162815666672 | 1.040815338027164 | 0.7043488656440638 | 0.85866246487436 | 0.8540757155696653 | +| 1.9948070155909097 | 2.0694147773526477 | 1.4018022880408287 | 1.7081998052886895 | 1.6990799175830091 | +| 2.222097749615152 | 3.5754621210435054 | 2.4225480514979942 | 2.952980403012079 | 2.937238656168783 | +| 2.449388483639394 | 5.629716271267176 | 3.819705958953274 | 4.652883297611153 | 4.628126242840219 | +| 2.6766792176636365 | 8.304748012039896 | 5.632753893882063 | 6.864448059729694 | 6.827994739946989 | +| 2.9039699516878787 | 11.658948498136947 | 7.914164276686367 | 9.641550437265021 | 9.590445775496226 | +| 3.131260685712121 | 15.760705467442335 | 10.700024516122776 | 13.035867911942523 | 12.966893547160572 | +| 3.3585514197363633 | 20.66935427188291 | 14.03336024608513 | 17.097218045933538 | 17.006901360934076 | +| 3.5858421537606056 | 26.446690457981603 | 17.957229993405374 | 21.873814320864742 | 21.758436130859106 | +| 3.813132887784848 | 33.14025069370375 | 22.510521678584603 | 27.41246562560744 | 27.268066840042437 | +| 4.04042362180909 | 40.80336296381522 | 27.71729992592343 | 33.75873567145005 | 33.58112314692881 | +| 4.267714355833332 | 49.49627653802831 | 33.62982414726785 | 40.95707296970886 | 40.741824711408505 | +| 4.495005089857575 | 59.277370431256216 | 40.28298497140692 | 49.0509185982613 | 48.793388426908514 | +| 4.722295823881817 | 70.19173971504746 | 47.688444274424846 | 58.08279682961652 | 57.77811860321969 | +| 4.949586557906059 | 82.28418674644324 | 55.91116293434267 | 68.09439228002755 | 67.73748373974462 | +| 5.176877291930301 | 95.61480106950536 | 64.96776364903921 | 79.12661628213944 | 78.71218257720365 | +| 5.404168025954544 | 110.21125322790957 | 74.90790585009226 | 91.21966451767037 | 90.742201453523 | +| 5.631458759978786 | 126.1353341808193 | 85.7370427422531 | 104.41306747208405 | 103.86686451768131 | +| 5.858749494003028 | 143.45745074915777 | 97.51424855078517 | 118.74573492802975 | 118.12487801197535 | +| 6.0860402280272705 | 162.22128746428191 | 110.26530060290307 | 134.25599545861493 | 133.554369578823 | +| 6.313330962051513 | 182.43749387245308 | 124.0007042994976 | 150.9816316890409 | 150.1929233567062 | + ### Plots +There are plenty of plots to expore with our Rating Curve Analysis. Under the **Rating Curve Results** tab we have our fitted stage-discharge curve plotted with the orginal data. + +![Stage-discharge rating curve fit, with measured pairs and Bayesian credible band.](./images/synthetic-rc-rating-curve.png) + +*Figure 1: Stage-discharge rating curve fit, with measured pairs and Bayesian credible band.* + +To explore how good the fit is we can look at our residuals in the **Residual Diagnostics** tab. The Residuals Plot shows the residuals of the dicharge values against the fitted stage values. + +![Residuals of measured discharge minus rating-curve estimate, plotted against stage.](./images/synthetic-rc-residuals.png) -![Stage-discharge rating curve fit, with measured pairs and Bayesian credible band.](images/synthetic-rc-rating-curve.png) -*Figure: Stage-discharge rating curve fit, with measured pairs and Bayesian credible band.* +*Figure 2: Residuals of measured discharge minus rating-curve estimate, plotted against stage.* -![Residuals of measured discharge minus rating-curve estimate, plotted against stage.](images/synthetic-rc-residuals.png) -*Figure: Residuals of measured discharge minus rating-curve estimate, plotted against stage.* +The **Markov Chain Traces** tab explores the traces of each Markov chain as it explores the posterior space in order to converge. -![Markov-chain traces for the rating-curve parameters.](images/synthetic-rc-trace.png) -*Figure: Markov-chain traces for the rating-curve parameters.* +![Markov-chain trace for the rating-curve parameter h₁, zero-flow stage.](./images/synthetic-rc-trace-h1.png) + +*Figure 3: Markov-chain trace for the rating-curve parameter h₁, zero-flow stage.* ### MCMC Diagnostics -Verify chain convergence before interpreting any results: +One should always verify chain convergence before interpreting any results. There are a variety of ways including: - **R-hat** — should be < 1.01 for every parameter. - **Effective Sample Size (ESS)** — at least a few hundred per parameter. - **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). - **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. +These can be found under the **Markov Chain Traces** and **MCMC Reports** tabs. + ## Next Steps - Use the Bayesian credible intervals to bound the rating curve at extreme stages. - Apply the rating curve to a stage time series (Time Series Data element) to derive a discharge time series. -- Refit with **more segments** if structural breaks in the data are visible in the residual plot. - -## References - - - ---- - -_This tutorial was generated from the project's `.bestfit` file metadata. The narrative and figure / table sections are placeholders — capture screenshots from the BestFit GUI and paste output tables to complete the guide._ +- Refit with **more segments** if structural breaks in the data are visible in the residual plot. \ No newline at end of file diff --git a/examples/6-rating-curve-analysis/USGS 01570500 Susquehanna River at Harrisburg, PA.bestfit.bak b/examples/6-rating-curve-analysis/usgs-01570500-susquehanna-rating-curve.bestfit similarity index 99% rename from examples/6-rating-curve-analysis/USGS 01570500 Susquehanna River at Harrisburg, PA.bestfit.bak rename to examples/6-rating-curve-analysis/usgs-01570500-susquehanna-rating-curve.bestfit index c792178..e1ef5e4 100644 Binary files a/examples/6-rating-curve-analysis/USGS 01570500 Susquehanna River at Harrisburg, PA.bestfit.bak and b/examples/6-rating-curve-analysis/usgs-01570500-susquehanna-rating-curve.bestfit differ diff --git a/examples/6-rating-curve-analysis/usgs-01570500-susquehanna-rating-curve.md b/examples/6-rating-curve-analysis/usgs-01570500-susquehanna-rating-curve.md index b08cf22..c92e55c 100644 --- a/examples/6-rating-curve-analysis/usgs-01570500-susquehanna-rating-curve.md +++ b/examples/6-rating-curve-analysis/usgs-01570500-susquehanna-rating-curve.md @@ -29,18 +29,17 @@ Stage-discharge rating curve for the Susquehanna River at Harrisburg, PA (USGS g ### Exploring the Elements -For each Rating Curve Analysis alternative: +For each Rating Curve Analysis: -1. Click the alternative in the Project Explorer. +1. Click the analysis in the Project Explorer. 2. Open the **Rating Curve** tab to view the fit overlaid on the measured stage / discharge pairs. -3. Adjust **MinStage**, **MaxStage**, and **StageBins** in the Properties panel to set the prediction range. -4. Inspect breakpoints (h2, h3) for multi-segment fits. +3. Adjust **MinStage**, **MaxStage**, and **StageBins** in the **Properties** panel under **Output** to set the prediction range. +4. Inspect breakpoints (h2, h3) behavior for multi-segment fits. ## Analysis Settings -Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any alternative to inspect: +Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any Rating Curve Analysis to inspect: -- **Sampler type** (DEMCzs, ARWMH, HMC). - **Iterations / Warm-up Iterations** — total post-warmup samples per chain. - **Number of Chains** — typically 6 for routine work. - **Thinning Interval** — keeps every Nth sample to reduce storage / autocorrelation. @@ -48,62 +47,88 @@ Each Bayesian analysis in this project uses the DEMCzs sampler with project-spec - **Credible Interval Width** — typically 0.90 or 0.95. ## Expected Results - - +Below are the expected results for Rating Curve Analysis labeled "USGS 01570500 Rating Curve"; this should be the only analysis in the list. ### Parameter Estimates +The parameter estimates are found under the **MCMC Report** tab to the left as parameter summary statistics. - - -| Alternative | Parameter | Mean | Median | Lower CI | Upper CI | R-hat | ESS | +| Parameter | Mean | Std Dev | 5% | Median | 95% |R-hat | ESS | |---|---|---|---|---|---|---|---| -| _(placeholder)_ | | | | | | | | +| Zero-Flow Stage (h₁) | 2.44039 | 0.0164549 | 2.41197 | 2.44128 | 2.46579 | 1.0001 | 9139 | +| Coefficient (α₁) | 3.96436 | 0.0122525 | 3.94376 | 3.96477 | 3.98379 | 1.0000 | 9574 | +| Exponent (β₁) | 1.38494 | 0.0151449 | 1.36035 | 1.38458 | 1.4101 | 0.9999 | 9974 | +| Scale (σ) | 0.0701198 | 0.00309255 | 0.0652849 | 0.0699853 | 0.0752692 | 0.9998 | 9889 | -### Frequency / Quantile Table - +### Frequency / Quantile Table +While in the **Rating Curve Results** tab to the left, select Tabular Results to see the fitted curve values. Below are the first 30 rows of the table. -| AEP (%) | Return Period (yr) | Median | Lower CI | Upper CI | +| Stage | 95.0% CI | 5.0% CI | Posterior Predictive | Posterior Mean | |---|---|---|---|---| -| 50 | 2 | | | | -| 10 | 10 | | | | -| 1 | 100 | | | | -| 0.5 | 200 | | | | -| 0.2 | 500 | | | | +| -0.45600000000000085 | 0 | 0 | 0 | 0 | +| -0.08436363636363714 | 0 | 0 | 0 | 0 | +| 0.28727272727272657 | 0 | 0 | 0 | 0 | +| 0.6589090909090902 | 0 | 0 | 0 | 0 | +| 1.030545454545454 | 0 | 0 | 0 | 0 | +| 1.4021818181818178 | 0 | 0 | 0 | 0 | +| 1.7738181818181815 | 0 | 0 | 0 | 0 | +| 2.145454545454545 | 0 | 0 | 0 | 0 | +| 2.517090909090909 | 410.12960132743984 | 151.87508813768804 | 266.15623259502286 | 262.9657731506839 | +| 2.8887272727272726 | 3971.982016764386 | 2325.0262202060535 | 3065.360870705832 | 3032.890388385699 | +| 3.2603636363636364 | 9151.094538089374 | 5375.701338618381 | 7074.5486749976335 | 6998.084920858722 | +| 3.632 | 15340.455815440519 | 9020.179796275253 | 11872.480974922595 | 11743.611844830442 | +| 4.003636363636364 | 22333.748844913265 | 13142.060614056078 | 17291.030763407693 | 17103.16337676947 | +| 4.375272727272727 | 30009.06156052017 | 17660.4544658233 | 23232.95384647871 | 22980.49385557292 | +| 4.7469090909090905 | 38265.817325339776 | 22512.86837712238 | 29633.181250236117 | 29311.190395279562 | +| 5.118545454545454 | 47061.69238012302 | 27700.58551851628 | 36444.42793122674 | 36048.441324163694 | +| 5.490181818181817 | 56338.554683823895 | 33178.007983298536 | 43630.432762026285 | 43156.34763762324 | +| 5.8618181818181805 | 66064.57709621015 | 38915.18433552818 | 51162.310025553525 | 50606.312046937375 | +| 6.233454545454544 | 76195.61450852503 | 44908.96799324281 | 59016.38645260097 | 58374.89792307115 | +| 6.605090909090907 | 86748.24265848288 | 51098.9660734954 | 67172.82836438731 | 66442.47020035432 | +| 6.9767272727272704 | 97665.47830414843 | 57531.15808242689 | 75614.72371260155 | 74792.28655537555 | +| 7.348363636363634 | 108886.05380527019 | 64174.45102292412 | 84327.4424959677 | 83409.86416204533 | +| 7.719999999999997 | 120478.71283824365 | 71005.36161485847 | 93298.17600172696 | 92282.52348551288 | +| 8.091636363636361 | 132428.09441208516 | 78011.73185585815 | 102515.59556253898 | 101399.0504039863 | +| 8.463272727272726 | 144703.78185673998 | 85155.71858423622 | 111969.59386799404 | 110749.44006799415 | +| 8.83490909090909 | 157180.90060800588 | 92494.72237830091 | 121651.0849140589 | 120324.69881875388 | +| 9.206545454545454 | 169960.86250388614 | 99968.03791720078 | 131551.8466116676 | 130116.6883454302 | +| 9.578181818181818 | 183059.71322994496 | 107662.33096474277 | 141664.3950811694 | 140118.00121654128 | +| 9.949818181818182 | 196413.87538077153 | 115431.68111328108 | 151981.88291419522 | 150321.8601432342 | +| 10.321454545454547 | 210025.9171024459 | 123454.0092924765 | 162498.01585849313 | 160722.03548458245 | +| 10.69309090909091 | 223740.3142318154 | 131602.71860607626 | 173206.98386802667 | 171312.7769771015 | ### Plots +There are plenty of plots to expore with our Rating Curve Analysis. Under the **Rating Curve Results** tab we have our fitted stage-discharge curve plotted with the orginal data. + +![Stage-discharge rating curve fit, with measured pairs and Bayesian credible band.](./images/susquehanna-rating-curve.png) + +*Figure 1: Stage-discharge rating curve fit, with measured pairs and Bayesian credible band.* + +To explore how good the fit is we can look at our residuals in the **Residual Diagnostics** tab. The Residuals Plot shows the residuals of the dicharge values against the fitted stage values. + +![Residuals of measured discharge minus rating-curve estimate, plotted against stage.](./images/susquehanna-residuals.png) -![Stage-discharge rating curve fit, with measured pairs and Bayesian credible band.](images/susquehanna-rating-curve.png) -*Figure: Stage-discharge rating curve fit, with measured pairs and Bayesian credible band.* +*Figure 2: Residuals of measured discharge minus rating-curve estimate, plotted against stage.* -![Residuals of measured discharge minus rating-curve estimate, plotted against stage.](images/susquehanna-residuals.png) -*Figure: Residuals of measured discharge minus rating-curve estimate, plotted against stage.* +The **Markov Chain Traces** tab explores the traces of each Markov chain as it explores the posterior space in order to converge. -![Markov-chain traces for the rating-curve parameters.](images/susquehanna-trace.png) -*Figure: Markov-chain traces for the rating-curve parameters.* +![Markov-chain trace for the rating-curve parameter h₁, zero-flow stage.](./images/susquehanna-trace-h1.png) + +*Figure 3: Markov-chain trace for the rating-curve parameter h₁, zero-flow stage.* ### MCMC Diagnostics -Verify chain convergence before interpreting any results: +One should always verify chain convergence before interpreting any results. There are a variety of ways including: - **R-hat** — should be < 1.01 for every parameter. - **Effective Sample Size (ESS)** — at least a few hundred per parameter. - **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). - **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. +These can be found under the **Markov Chain Traces** and **MCMC Reports** tabs. + ## Next Steps - Use the Bayesian credible intervals to bound the rating curve at extreme stages. - Apply the rating curve to a stage time series (Time Series Data element) to derive a discharge time series. -- Refit with **more segments** if structural breaks in the data are visible in the residual plot. - -## References - - - ---- - -_This tutorial was generated from the project's `.bestfit` file metadata. The narrative and figure / table sections are placeholders — capture screenshots from the BestFit GUI and paste output tables to complete the guide._ +- Refit with **more segments** if structural breaks in the data are visible in the residual plot. \ No newline at end of file diff --git a/examples/6-rating-curve-analysis/usgs-07024175-mississippi-rating-curve.bestfit b/examples/6-rating-curve-analysis/usgs-07024175-mississippi-rating-curve.bestfit index 4345f00..6df9362 100644 Binary files a/examples/6-rating-curve-analysis/usgs-07024175-mississippi-rating-curve.bestfit and b/examples/6-rating-curve-analysis/usgs-07024175-mississippi-rating-curve.bestfit differ diff --git a/examples/6-rating-curve-analysis/usgs-07024175-mississippi-rating-curve.md b/examples/6-rating-curve-analysis/usgs-07024175-mississippi-rating-curve.md index 3e3b74f..2f32846 100644 --- a/examples/6-rating-curve-analysis/usgs-07024175-mississippi-rating-curve.md +++ b/examples/6-rating-curve-analysis/usgs-07024175-mississippi-rating-curve.md @@ -29,18 +29,17 @@ Stage-discharge rating curve for the Mississippi River at New Madrid, MO (USGS g ### Exploring the Elements -For each Rating Curve Analysis alternative: +For each Rating Curve Analysis: -1. Click the alternative in the Project Explorer. +1. Click the analysis in the Project Explorer. 2. Open the **Rating Curve** tab to view the fit overlaid on the measured stage / discharge pairs. -3. Adjust **MinStage**, **MaxStage**, and **StageBins** in the Properties panel to set the prediction range. -4. Inspect breakpoints (h2, h3) for multi-segment fits. +3. Adjust **MinStage**, **MaxStage**, and **StageBins** in the **Properties** panel under **Output** to set the prediction range. +4. Inspect breakpoints (h2, h3) behavior for multi-segment fits. ## Analysis Settings -Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any alternative to inspect: +Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any Rating Curve Analysis to inspect: -- **Sampler type** (DEMCzs, ARWMH, HMC). - **Iterations / Warm-up Iterations** — total post-warmup samples per chain. - **Number of Chains** — typically 6 for routine work. - **Thinning Interval** — keeps every Nth sample to reduce storage / autocorrelation. @@ -48,62 +47,87 @@ Each Bayesian analysis in this project uses the DEMCzs sampler with project-spec - **Credible Interval Width** — typically 0.90 or 0.95. ## Expected Results - - +Below are the expected results for Rating Curve Analysis labeled "USGS 07024175 Rating Curve"; this should be the only analysis in the list. ### Parameter Estimates +The parameter estimates are found under the **MCMC Report** tab to the left as parameter summary statistics. - - -| Alternative | Parameter | Mean | Median | Lower CI | Upper CI | R-hat | ESS | +| Parameter | Mean | Std Dev | 5% | Median | 95% |R-hat | ESS | |---|---|---|---|---|---|---|---| -| _(placeholder)_ | | | | | | | | +| Zero-Flow Stage (h₁) | -50.9737 | 1.41209 | -52.4399 | -51.3797 | -48.1138 | 1.0003 | 7963 | +| Coefficient (α₁) | -0.247074 | 0.167744 | -0.446818 | -0.285831 | 0.0819723 | 1.0001 | 8212 | +| Exponent (β₁) | 3.25476 | 0.0765488 | 3.10656 | 3.27074 | 3.34947 | 1.0001 | 8212 | +| Scale (σ) | 0.0232005 | 0.00174484 | 0.0205575 | 0.0230843 | 0.0262762 | 1.0000 | 8839 | ### Frequency / Quantile Table +While in the **Rating Curve Results** tab to the left, select Tabular Results to see the fitted curve values. Below are the first 30 rows of the table. - - -| AEP (%) | Return Period (yr) | Median | Lower CI | Upper CI | +| Stage | 95.0% CI | 5.0% CI | Posterior Predictive | Posterior Mean | |---|---|---|---|---| -| 50 | 2 | | | | -| 10 | 10 | | | | -| 1 | 100 | | | | -| 0.5 | 200 | | | | -| 0.2 | 500 | | | | +| -10.32 | 107233.48891328025 | 89252.44853582536 | 97882.67401248094 | 97759.59878226908 | +| -9.751515151515152 | 112172.76090829527 | 93377.98975839319 | 102409.32164524312 | 102279.5145581598 | +| -9.183030303030304 | 117253.96542707036 | 97640.07304896398 | 107078.94336402623 | 106942.1838946469 | +| -8.614545454545455 | 122500.95875572132 | 102054.03832586182 | 111894.01551078865 | 111750.08131880655 | +| -8.046060606060607 | 127890.56193725689 | 106606.6364913999 | 116857.02301816594 | 116705.6899486076 | +| -7.477575757575758 | 133438.95034031325 | 111309.80867250207 | 121970.45932662637 | 121811.50140683203 | +| -6.90909090909091 | 139180.48496136305 | 116120.46020672606 | 127236.82630351723 | 127070.01573698898 | +| -6.340606060606062 | 145096.5650285967 | 121118.93112461768 | 132658.63416393162 | 132483.74132115053 | +| -5.772121212121213 | 151180.01910969758 | 126219.27592831891 | 138238.40139333345 | 138055.19479964004 | +| -5.203636363636365 | 157427.82875562625 | 131494.12946011117 | 143978.6546718787 | 143786.90099250973 | +| -4.635151515151517 | 163884.41464408263 | 136892.50742681848 | 149881.92880037543 | 149681.3928227443 | +| -4.066666666666668 | 170512.41057897243 | 142467.8016645793 | 155950.76662782748 | 155741.2112411322 | +| -3.49818181818182 | 177330.61671481933 | 148176.6060519974 | 162187.7189805075 | 161968.90515274883 | +| -2.9296969696969715 | 184338.32190598545 | 154043.2946927888 | 168595.34459251 | 168367.03134499607 | +| -2.361212121212123 | 191544.69904533925 | 160057.6919361752 | 175176.2100377358 | 174938.1544171493 | +| -1.7927272727272747 | 198929.62166599787 | 166221.51788061377 | 181932.8896632624 | 181684.8467113616 | +| -1.2242424242424264 | 206522.26096658685 | 172551.67600688594 | 188867.9655240547 | 188609.68824507756 | +| -0.6557575757575779 | 214262.00326850175 | 179085.99821003486 | 195984.02731897478 | 195715.26664481362 | +| -0.08727272727272939 | 222213.24909972525 | 185772.66122881282 | 203283.67232805074 | 203004.1770812607 | +| 0.4812121212121191 | 230375.92431337215 | 192627.1154367028 | 210769.50535096496 | 210479.0222056684 | +| 1.0496969696969676 | 238769.8553911058 | 199651.54465301434 | 218444.1386467255 | 218142.4120874721 | +| 1.618181818181816 | 247359.77250322487 | 206855.60670217167 | 226310.19187448363 | 225996.9641531231 | +| 2.1866666666666643 | 256134.09194474702 | 214269.8842207569 | 234370.2920354657 | 234045.30312608884 | +| 2.7551515151515127 | 265118.53833764564 | 221924.51001557292 | 242627.07341598434 | 242290.0609679854 | +| 3.323636363636361 | 274355.3979176643 | 229689.27004171046 | 251083.17753149863 | 250733.87682081136 | +| 3.8921212121212094 | 283857.78469559737 | 237565.3026476537 | 259741.25307169303 | 259379.3969502485 | +| 4.460606060606058 | 293473.7527909951 | 245676.13656637978 | 268603.95584654587 | 268229.27469000156 | +| 5.029090909090907 | 303341.5539648264 | 254024.34969453176 | 277673.9487333584 | 277286.1703871448 | +| 5.597575757575755 | 313490.936832673 | 262533.73442931875 | 286953.9016247211 | 286552.7513484489 | +| 6.166060606060603 | 323883.36784028145 | 271216.1227831109 | 296446.49137738615 | 296031.6917876595 | +| 6.734545454545452 | 334437.7400930983 | 280120.2952789973 | 306154.40176202514 | 305725.6727737018 | ### Plots +There are plenty of plots to expore with our Rating Curve Analysis. Under the **Rating Curve Results** tab we have our fitted stage-discharge curve plotted with the orginal data. + +![Stage-discharge rating curve fit, with measured pairs and Bayesian credible band.](./images/mississippi-rating-curve.png) + +*Figure 1: Stage-discharge rating curve fit, with measured pairs and Bayesian credible band.* + +To explore how good the fit is we can look at our residuals in the **Residual Diagnostics** tab. The Residuals Plot shows the residuals of the dicharge values against the fitted stage values. + +![Residuals of measured discharge minus rating-curve estimate, plotted against stage.](./images/mississippi-residuals.png) -![Stage-discharge rating curve fit, with measured pairs and Bayesian credible band.](images/mississippi-rating-curve.png) -*Figure: Stage-discharge rating curve fit, with measured pairs and Bayesian credible band.* +*Figure 2: Residuals of measured discharge minus rating-curve estimate, plotted against stage.* -![Residuals of measured discharge minus rating-curve estimate, plotted against stage.](images/mississippi-residuals.png) -*Figure: Residuals of measured discharge minus rating-curve estimate, plotted against stage.* +The **Markov Chain Traces** tab explores the traces of each Markov chain as it explores the posterior space in order to converge. -![Markov-chain traces for the rating-curve parameters.](images/mississippi-trace.png) -*Figure: Markov-chain traces for the rating-curve parameters.* +![Markov-chain trace for the rating-curve parameter h₁, zero-flow stage.](./images/mississippi-trace-h1.png) + +*Figure 3: Markov-chain trace for the rating-curve parameter h₁, zero-flow stage.* ### MCMC Diagnostics -Verify chain convergence before interpreting any results: +One should always verify chain convergence before interpreting any results. There are a variety of ways including: - **R-hat** — should be < 1.01 for every parameter. - **Effective Sample Size (ESS)** — at least a few hundred per parameter. - **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). - **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. +These can be found under the **Markov Chain Traces** and **MCMC Reports** tabs. + ## Next Steps - Use the Bayesian credible intervals to bound the rating curve at extreme stages. - Apply the rating curve to a stage time series (Time Series Data element) to derive a discharge time series. - Refit with **more segments** if structural breaks in the data are visible in the residual plot. - -## References - - - ---- - -_This tutorial was generated from the project's `.bestfit` file metadata. The narrative and figure / table sections are placeholders — capture screenshots from the BestFit GUI and paste output tables to complete the guide._ diff --git a/examples/6-rating-curve-analysis/usgs-14145000-willamette-rating-curve.md b/examples/6-rating-curve-analysis/usgs-14145000-willamette-rating-curve.md deleted file mode 100644 index a4a0bfc..0000000 --- a/examples/6-rating-curve-analysis/usgs-14145000-willamette-rating-curve.md +++ /dev/null @@ -1,109 +0,0 @@ -# usgs-14145000-willamette-rating-curve - -## Overview - -Stage-discharge rating curve for the Middle Fork Willamette River (USGS gage 14145000), fit using the piecewise power-law rating curve model with Bayesian MCMC. - -## What's Inside - -### Time Series Data - -| Element | Description | -|---|---| -| `Stage Data` | Field-measured (rated) gage height for the Middle Fork Willamette River (USGS gage 14145000). | -| `Discharge Data` | Field-measured (rated) discharge for the Middle Fork Willamette River (USGS gage 14145000). | - -### Rating Curve Analysis - -| Element | Description | -|---|---| -| `USGS 14145000 Rating Curve` | Bayesian piecewise power-law rating-curve fit to the field-measured stage-discharge pairs at the Middle Fork Willamette River. | - -## Step-by-Step Walkthrough - -### Opening the Project - -1. Open RMC-BestFit 2.0. -2. Select **File > Open** and navigate to `examples/6-rating-curve-analysis/`. -3. Open `usgs-14145000-willamette-rating-curve.bestfit`. - -### Exploring the Elements - -For each Rating Curve Analysis alternative: - -1. Click the alternative in the Project Explorer. -2. Open the **Rating Curve** tab to view the fit overlaid on the measured stage / discharge pairs. -3. Adjust **MinStage**, **MaxStage**, and **StageBins** in the Properties panel to set the prediction range. -4. Inspect breakpoints (h2, h3) for multi-segment fits. - -## Analysis Settings - -Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any alternative to inspect: - -- **Sampler type** (DEMCzs, ARWMH, HMC). -- **Iterations / Warm-up Iterations** — total post-warmup samples per chain. -- **Number of Chains** — typically 6 for routine work. -- **Thinning Interval** — keeps every Nth sample to reduce storage / autocorrelation. -- **Point Estimator** — Posterior Mean (default), Posterior Median, or Posterior Mode (MAP). -- **Credible Interval Width** — typically 0.90 or 0.95. - -## Expected Results - - - -### Parameter Estimates - - - -| Alternative | Parameter | Mean | Median | Lower CI | Upper CI | R-hat | ESS | -|---|---|---|---|---|---|---|---| -| _(placeholder)_ | | | | | | | | - -### Frequency / Quantile Table - - - -| AEP (%) | Return Period (yr) | Median | Lower CI | Upper CI | -|---|---|---|---|---| -| 50 | 2 | | | | -| 10 | 10 | | | | -| 1 | 100 | | | | -| 0.5 | 200 | | | | -| 0.2 | 500 | | | | - -### Plots - -![Stage-discharge rating curve fit, with measured pairs and Bayesian credible band.](images/willamette-rating-curve.png) -*Figure: Stage-discharge rating curve fit, with measured pairs and Bayesian credible band.* - -![Residuals of measured discharge minus rating-curve estimate, plotted against stage.](images/willamette-residuals.png) -*Figure: Residuals of measured discharge minus rating-curve estimate, plotted against stage.* - -![Markov-chain traces for the rating-curve parameters.](images/willamette-trace.png) -*Figure: Markov-chain traces for the rating-curve parameters.* - -### MCMC Diagnostics - -Verify chain convergence before interpreting any results: - -- **R-hat** — should be < 1.01 for every parameter. -- **Effective Sample Size (ESS)** — at least a few hundred per parameter. -- **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). -- **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. - -## Next Steps - -- Use the Bayesian credible intervals to bound the rating curve at extreme stages. -- Apply the rating curve to a stage time series (Time Series Data element) to derive a discharge time series. -- Refit with **more segments** if structural breaks in the data are visible in the residual plot. - -## References - - - ---- - -_This tutorial was generated from the project's `.bestfit` file metadata. The narrative and figure / table sections are placeholders — capture screenshots from the BestFit GUI and paste output tables to complete the guide._ diff --git a/examples/7-time-series-analysis/1-synthetic-data-examples/synthetic-time-series-examples.md b/examples/7-time-series-analysis/1-synthetic-data-examples/synthetic-time-series-examples.md deleted file mode 100644 index fe9abf0..0000000 --- a/examples/7-time-series-analysis/1-synthetic-data-examples/synthetic-time-series-examples.md +++ /dev/null @@ -1,132 +0,0 @@ -# synthetic-time-series-examples - -## Overview - -Synthetic time-series datasets covering trend (linear, quadratic, cubic, sinusoidal), AR / MA / ARMA processes, and a log-transformed series with linear trend. Each series has a paired Time Series Analysis fit using the corresponding model for verifying parameter recovery. - -## What's Inside - -### Time Series Data - -| Element | Description | -|---|---| -| `Intercept` | Synthetic series with constant mean only (no trend, no autocorrelation). | -| `Intercept + Linear Trend` | Synthetic series with constant mean + linear trend. | -| `Intercept + Quadratic Trend` | Synthetic series with constant mean + quadratic trend. | -| `Intercept + Cubic Trend` | Synthetic series with constant mean + cubic trend. | -| `Intercept + Sinusoidal Trend` | Synthetic series with constant mean + sinusoidal (annual cycle) trend. | -| `AR(1)` | Synthetic AR(1) series for AR-fit verification. | -| `AR(3)` | Synthetic AR(3) series for AR-fit verification. | -| `MA(1)` | Synthetic MA(1) series for MA-fit verification. | -| `MA(3)` | Synthetic MA(3) series for MA-fit verification. | -| `ARMA(1,1)` | Synthetic ARMA(1,1) series for ARMA-fit verification. | -| `ARMA(2,2)` | Synthetic ARMA(2,2) series for ARMA-fit verification. | -| `Intercept + Linear Trend + ARMA(1,1)` | Synthetic series with constant mean + linear trend + ARMA(1,1) residuals. | -| `Intercept + Linear Trend + LogTransform` | Log-normal synthetic series with constant mean + linear trend (in log space). | - -### Time Series Analysis - -| Element | Description | -|---|---| -| `Intercept` | Constant-mean fit on the intercept-only synthetic series. | -| `Intercept + Linear Trend` | Linear-trend fit on the intercept + linear trend synthetic series. | -| `Intercept + Quadratic Trend` | Quadratic-trend fit on the intercept + quadratic trend synthetic series. | -| `Intercept + Cubic Trend` | Cubic-trend fit on the intercept + cubic trend synthetic series. | -| `Intercept + Sinusoidal Trend` | Sinusoidal-trend fit on the intercept + sinusoidal trend synthetic series. | -| `AR(1)` | AR(1) fit on the AR(1) synthetic series. | -| `AR(3)` | AR(3) fit on the AR(3) synthetic series. | -| `MA(1)` | MA(1) fit on the MA(1) synthetic series. | -| `MA(3)` | MA(3) fit on the MA(3) synthetic series. | -| `ARMA(1,1)` | ARMA(1,1) fit on the ARMA(1,1) synthetic series. | -| `ARMA(2,2)` | ARMA(2,2) fit on the ARMA(2,2) synthetic series. | -| `Intercept + Linear Trend + ARMA(1,1)` | Linear-trend + ARMA(1,1) fit on the corresponding synthetic series. | -| `Intercept + Linear Trend + LogTransform` | Linear-trend fit with logarithmic transform on the log-normal synthetic series. | - -## Step-by-Step Walkthrough - -### Opening the Project - -1. Open RMC-BestFit 2.0. -2. Select **File > Open** and navigate to `examples/7-time-series-analysis/1-synthetic-data-examples/`. -3. Open `synthetic-time-series-examples.bestfit`. - -### Exploring the Elements - -For each Time Series Analysis alternative: - -1. Click the alternative in the Project Explorer. -2. Open the **Time Series** tab to view the fitted mean (and trend, if any) overlaid on the observations. -3. Open the **Residual ACF / PACF** tabs to confirm white-noise residuals. -4. Adjust **ForecastSteps** in the Properties panel to extend the forecast horizon. - -## Analysis Settings - -Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any alternative to inspect: - -- **Sampler type** (DEMCzs, ARWMH, HMC). -- **Iterations / Warm-up Iterations** — total post-warmup samples per chain. -- **Number of Chains** — typically 6 for routine work. -- **Thinning Interval** — keeps every Nth sample to reduce storage / autocorrelation. -- **Point Estimator** — Posterior Mean (default), Posterior Median, or Posterior Mode (MAP). -- **Credible Interval Width** — typically 0.90 or 0.95. - -## Expected Results - - - -### Parameter Estimates - - - -| Alternative | Parameter | Mean | Median | Lower CI | Upper CI | R-hat | ESS | -|---|---|---|---|---|---|---|---| -| _(placeholder)_ | | | | | | | | - -### Frequency / Quantile Table - - - -| AEP (%) | Return Period (yr) | Median | Lower CI | Upper CI | -|---|---|---|---|---| -| 50 | 2 | | | | -| 10 | 10 | | | | -| 1 | 100 | | | | -| 0.5 | 200 | | | | -| 0.2 | 500 | | | | - -### Plots - -![Time-series fit overlaid on the observations, with credible band.](images/synthetic-ts-time-series.png) -*Figure: Time-series fit overlaid on the observations, with credible band.* - -![Multi-step forecast extension with credible band.](images/synthetic-ts-forecast.png) -*Figure: Multi-step forecast extension with credible band.* - -![Residual autocorrelation function.](images/synthetic-ts-acf.png) -*Figure: Residual autocorrelation function.* - -### MCMC Diagnostics - -Verify chain convergence before interpreting any results: - -- **R-hat** — should be < 1.01 for every parameter. -- **Effective Sample Size (ESS)** — at least a few hundred per parameter. -- **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). -- **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. - -## Next Steps - -- Use the fitted ARIMA / regression model for **multi-step forecasting** with credible bands. -- Inspect residual ACF / PACF to confirm no remaining temporal structure. -- For non-stationary trend cases, project the trend function out beyond the observation window. - -## References - - - ---- - -_This tutorial was generated from the project's `.bestfit` file metadata. The narrative and figure / table sections are placeholders — capture screenshots from the BestFit GUI and paste output tables to complete the guide._ diff --git a/examples/7-time-series-analysis/2-classic-time-series-examples/classic-time-series-examples.md b/examples/7-time-series-analysis/2-classic-time-series-examples/classic-time-series-examples.md deleted file mode 100644 index a721ab3..0000000 --- a/examples/7-time-series-analysis/2-classic-time-series-examples/classic-time-series-examples.md +++ /dev/null @@ -1,170 +0,0 @@ -# Manual Data Entry Example - -## Overview - -This example demonstrates how to enter time series data manually in RMC-BestFit by copy-pasting from CSV files. The project contains three classic datasets widely used in time series analysis textbooks and statistical software documentation. - -Manual entry is useful when your data comes from published tables, spreadsheets, or other sources not covered by the built-in download options (USGS, GHCN, CHMN, ABOM, HEC-DSS). - -## Datasets - -| Element | Dataset | Frequency | Period | Unit Label | Source | -|---------|---------|-----------|--------|------------|--------| -| Airline Passengers | Box-Jenkins airline data | Monthly | 1949--1960 | Passengers (thousands) | Box & Jenkins (1970) | -| Nile River Flows | Nile annual flow at Aswan | Annual | 1871--1970 | Flow (10⁸ m³) | Cobb (1978) | -| Mauna Loa CO2 | Atmospheric CO2 at Mauna Loa | Monthly | 1958--2023 | CO2 (ppm) | NOAA GML | - -### Airline Passengers - -The Box-Jenkins airline passenger dataset records monthly totals of international airline passengers from 1949 to 1960. It is one of the most widely used examples in time series analysis, originally published in *Time Series Analysis: Forecasting and Control* (Box & Jenkins, 1970). The series exhibits: - -- **Strong seasonality** with peaks in summer months (June--August) -- **Multiplicative trend** -- the seasonal amplitude grows proportionally with the level -- **Upward trend** reflecting growth in commercial aviation - -This dataset is commonly used to demonstrate seasonal ARIMA (SARIMA) modeling, seasonal differencing, and log transformations for variance stabilization. - -### Nile River Flows - -The Nile River dataset records annual flow volumes at Aswan from 1871 to 1970, measured in units of 10⁸ cubic meters. Published by Cobb (1978) and widely used in the R `datasets` package, the series is notable for: - -- **A level shift around 1898** coinciding with the construction of the first Aswan Dam -- **Low-order autocorrelation** suitable for AR(1) modeling -- **Change-point detection** -- the abrupt shift makes this a classic example for structural break analysis - -The annual frequency and level shift make this dataset ideal for introducing autoregressive models and change-point methods. - -### Mauna Loa CO2 - -Monthly average atmospheric CO2 concentrations recorded at the Mauna Loa Observatory in Hawaii, maintained by the NOAA Global Monitoring Laboratory (GML). This is the longest continuous record of directly measured atmospheric CO2 and is widely known as the Keeling Curve. The series exhibits: - -- **Strong upward trend** driven by fossil fuel emissions -- **Regular seasonal cycle** caused by Northern Hemisphere vegetation uptake in spring/summer -- **Nonlinear trend** -- the rate of increase accelerates over the record - -This dataset is commonly used to demonstrate seasonal decomposition, trend-cycle separation, and ARIMAX modeling with deterministic seasonal components. - -## What's Inside - -Open `manual-entry-example.bestfit` in RMC-BestFit. The Project Explorer shows three Time Series Data elements: - -![Project Explorer showing the three manual entry elements: Airline Passengers, Nile River Flows, and Mauna Loa CO2](../images/manual-entry-project-explorer.png) -*Figure 1: Project Explorer with three manually entered time series* - -Each element contains the full dataset already entered. Click on any element to view the time series plot and explore its statistical properties. - -## Step-by-Step Guide - -### Opening the Project - -1. Launch RMC-BestFit 2.0 -2. Select **File > Open** and navigate to this folder -3. Open `manual-entry-example.bestfit` -4. Expand **Time Series Data** in the Project Explorer - -### Exploring the Time Series Tabs - -Click on an element to open it. The main view shows four tabs: - -1. **Time Series** -- The raw data plotted against time. Look for trend, seasonality, and level shifts. -2. **Seasonality** -- A seasonal subseries plot showing data grouped by month (or other period). Useful for identifying recurring patterns. -3. **ACF** -- Autocorrelation function. Slowly decaying ACF suggests trend or nonstationarity; periodic peaks suggest seasonality. -4. **PACF** -- Partial autocorrelation function. Helps identify AR order -- significant spikes at lags 1 through *p* suggest an AR(*p*) model. - -![Time series plot of Airline Passengers showing upward trend with growing seasonal amplitude](../images/manual-entry-airline-ts-plot.png) -*Figure 2: Airline Passengers time series showing multiplicative seasonal pattern* - -![ACF plot of Airline Passengers showing slowly decaying autocorrelation with seasonal peaks](../images/manual-entry-airline-acf.png) -*Figure 3: ACF of Airline Passengers -- periodic peaks at lags 12, 24, 36 indicate seasonality* - -![Time series plot of Nile River Flows showing level shift around 1898](../images/manual-entry-nile-ts-plot.png) -*Figure 4: Nile River annual flows with visible level shift* - -![Time series plot of Mauna Loa CO2 showing upward trend with seasonal cycle](../images/manual-entry-co2-ts-plot.png) -*Figure 5: Mauna Loa CO2 with accelerating trend and annual seasonal cycle* - -### Viewing the Properties Panel - -Open the Properties panel (click **Properties** in the toolbar or press **F4**) to see the configuration for each element: - -- **Entry Method** -- Set to *Manual* for all three elements -- **Time Interval** -- *One Month* for Airline Passengers and Mauna Loa CO2; *One Year* for Nile River Flows -- **Unit Label** -- Displayed on the Y-axis of the time series plot -- **Start Date** -- The date of the first observation - -![Properties panel showing Entry Method = Manual, Time Interval = One Month, and Unit Label for Airline Passengers](../images/manual-entry-properties.png) -*Figure 6: Properties panel for a manually entered time series* - -## Creating Your Own Manual Entry Element - -To enter a new time series manually from a CSV file: - -### 1. Create the Element - -1. Right-click **Time Series Data** in the Project Explorer -2. Select **Create New** -3. Enter a descriptive name for the element - -### 2. Configure the Properties - -In the Properties panel: - -1. Set **Entry Method** to *Manual* -2. Set **Time Interval** to match your data frequency (e.g., *One Month*, *One Year*, *One Day*) -3. Set **Start Date** to the date of the first observation -4. Set **Unit Label** to describe the data units (e.g., "Discharge (cfs)", "Precipitation (mm)") - -### 3. Paste the Data - -1. Open the CSV file in a spreadsheet application or text editor -2. Select the **value column only** (not the date column -- dates are computed from the Start Date and Time Interval) -3. Copy the values to the clipboard -4. In RMC-BestFit, click on the data grid in the Time Series tab -5. Select the first cell in the **Value** column -6. Paste (**Ctrl+V**) - -The dates are automatically generated based on the Start Date and Time Interval settings. For regular-interval data (monthly, annual, daily), you only need to paste the values. - -### 4. Verify - -After pasting, check: - -- The time series plot updates to show your data -- The date range matches your expected period of record -- The number of observations matches your source data -- The Y-axis label shows your Unit Label - -## CSV Files Provided - -Three CSV files are included in this folder for reference and practice: - -| File | Columns | Rows | -|------|---------|------| -| `airline-passengers.csv` | Date, Passengers | 144 | -| `nile-river-flow.csv` | Date, Flow | 100 | -| `mauna-loa-co2.csv` | Date, CO2 | 790 | - -Each file uses a simple two-column format with ISO date strings (YYYY-MM-DD) and numeric values. The Date column is provided for reference -- when pasting into RMC-BestFit, you only need the value column. - -## Key Settings Reference - -| Setting | Purpose | Example Values | -|---------|---------|---------------| -| Entry Method | How data is entered | Manual, USGS, GHCN, CHMN, ABOM, HEC-DSS | -| Time Interval | Spacing between observations | One Month, One Year, One Day, One Hour | -| Start Date | Date of the first observation | 1949-01-01, 1871-01-01 | -| Unit Label | Y-axis label and data description | Passengers (thousands), Flow (10⁸ m³), CO2 (ppm) | - -## Next Steps - -After entering time series data, continue with: - -1. **Input Data** -- Create an Input Data element that references a time series, apply a block function (e.g., annual maximum), and extract the sample for frequency analysis -2. **Time Series Analysis** -- Fit ARIMA/ARIMAX models to the raw time series for forecasting and trend analysis (see examples in `../../7-time-series-analysis/`) -3. **Distribution Fitting** -- Fit multiple distributions to the extracted sample and compare goodness-of-fit - -## References - -- Box, G. E. P., & Jenkins, G. M. (1970). *Time Series Analysis: Forecasting and Control*. Holden-Day. -- Cobb, G. W. (1978). The Problem of the Nile: Conditional Solution to a Changepoint Problem. *Biometrika*, 65(2), 243--251. -- NOAA Global Monitoring Laboratory. Trends in Atmospheric Carbon Dioxide. https://gml.noaa.gov/ccgg/trends/ diff --git a/examples/7-time-series-analysis/3-time-series-regression-example/time-series-regression-example.md b/examples/7-time-series-analysis/3-time-series-regression-example/time-series-regression-example.md deleted file mode 100644 index 4f02d1a..0000000 --- a/examples/7-time-series-analysis/3-time-series-regression-example/time-series-regression-example.md +++ /dev/null @@ -1,113 +0,0 @@ -# time-series-regression-example - -## Overview - -Multivariate time-series regression on classic US macroeconomic indicators (consumption, income, production, savings, unemployment). Demonstrates simple and multiple linear regression with autocorrelated residuals. - -## What's Inside - -### Time Series Data - -| Element | Description | -|---|---| -| `Consumption` | Quarterly US personal consumption expenditures (response variable for the regression examples). | -| `Income` | Quarterly US personal disposable income (regressor). | -| `Production` | Quarterly US industrial production index (regressor). | -| `Savings` | Quarterly US personal savings rate (regressor). | -| `Unemployment` | Quarterly US unemployment rate (regressor). | - -### Time Series Analysis - -| Element | Description | -|---|---| -| `Simple Linear Regression` | Simple linear regression of consumption on income, with autocorrelated residuals modeled as ARMA. | -| `Multiple Linear Regression` | Multiple linear regression of consumption on income, production, savings, and unemployment, with autocorrelated residuals modeled as ARMA. | - -## Step-by-Step Walkthrough - -### Opening the Project - -1. Open RMC-BestFit 2.0. -2. Select **File > Open** and navigate to `examples/7-time-series-analysis/3-time-series-regression-example/`. -3. Open `time-series-regression-example.bestfit`. - -### Exploring the Elements - -For each Time Series Analysis alternative: - -1. Click the alternative in the Project Explorer. -2. Open the **Time Series** tab to view the fitted mean (and trend, if any) overlaid on the observations. -3. Open the **Residual ACF / PACF** tabs to confirm white-noise residuals. -4. Adjust **ForecastSteps** in the Properties panel to extend the forecast horizon. - -## Analysis Settings - -Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any alternative to inspect: - -- **Sampler type** (DEMCzs, ARWMH, HMC). -- **Iterations / Warm-up Iterations** — total post-warmup samples per chain. -- **Number of Chains** — typically 6 for routine work. -- **Thinning Interval** — keeps every Nth sample to reduce storage / autocorrelation. -- **Point Estimator** — Posterior Mean (default), Posterior Median, or Posterior Mode (MAP). -- **Credible Interval Width** — typically 0.90 or 0.95. - -## Expected Results - - - -### Parameter Estimates - - - -| Alternative | Parameter | Mean | Median | Lower CI | Upper CI | R-hat | ESS | -|---|---|---|---|---|---|---|---| -| _(placeholder)_ | | | | | | | | - -### Frequency / Quantile Table - - - -| AEP (%) | Return Period (yr) | Median | Lower CI | Upper CI | -|---|---|---|---|---| -| 50 | 2 | | | | -| 10 | 10 | | | | -| 1 | 100 | | | | -| 0.5 | 200 | | | | -| 0.2 | 500 | | | | - -### Plots - -![Time-series fit overlaid on the observations, with credible band.](images/ts-regression-time-series.png) -*Figure: Time-series fit overlaid on the observations, with credible band.* - -![Multi-step forecast extension with credible band.](images/ts-regression-forecast.png) -*Figure: Multi-step forecast extension with credible band.* - -![Residual autocorrelation function.](images/ts-regression-acf.png) -*Figure: Residual autocorrelation function.* - -### MCMC Diagnostics - -Verify chain convergence before interpreting any results: - -- **R-hat** — should be < 1.01 for every parameter. -- **Effective Sample Size (ESS)** — at least a few hundred per parameter. -- **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). -- **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. - -## Next Steps - -- Use the fitted ARIMA / regression model for **multi-step forecasting** with credible bands. -- Inspect residual ACF / PACF to confirm no remaining temporal structure. -- For non-stationary trend cases, project the trend function out beyond the observation window. - -## References - - - ---- - -_This tutorial was generated from the project's `.bestfit` file metadata. The narrative and figure / table sections are placeholders — capture screenshots from the BestFit GUI and paste output tables to complete the guide._ diff --git a/examples/7-time-series-analysis/README.md b/examples/7-time-series-analysis/README.md index b7cd575..ab30006 100644 --- a/examples/7-time-series-analysis/README.md +++ b/examples/7-time-series-analysis/README.md @@ -60,10 +60,6 @@ Each Time Series Analysis element references **one** Time Series Data element as By default, RMC-BestFit reserves the **last 20% of each series for validation** (`UseDefaultTrainingSteps = true`). For maximum-likelihood parity with R's `arima()` and statsmodels, set `UseDefaultTrainingSteps = false` and `TrainingTimeSteps = data length` in the Properties panel. -## Screenshot Images - -Capture screenshots into `images/` subfolders next to each example. Naming convention: `-.png` (e.g., `nile-time-series.png`, `synthetic-ts-arma11-residuals.png`). - ## Next Steps After fitting a time-series model: diff --git a/examples/7-time-series-analysis/1-synthetic-data-examples/Synthetic Data.xlsx b/examples/7-time-series-analysis/Synthetic Data.xlsx similarity index 100% rename from examples/7-time-series-analysis/1-synthetic-data-examples/Synthetic Data.xlsx rename to examples/7-time-series-analysis/Synthetic Data.xlsx diff --git a/examples/7-time-series-analysis/2-classic-time-series-examples/airline-passengers.csv b/examples/7-time-series-analysis/airline-passengers.csv similarity index 100% rename from examples/7-time-series-analysis/2-classic-time-series-examples/airline-passengers.csv rename to examples/7-time-series-analysis/airline-passengers.csv diff --git a/examples/7-time-series-analysis/2-classic-time-series-examples/classic-time-series-examples.bestfit b/examples/7-time-series-analysis/classic-time-series-examples.bestfit similarity index 99% rename from examples/7-time-series-analysis/2-classic-time-series-examples/classic-time-series-examples.bestfit rename to examples/7-time-series-analysis/classic-time-series-examples.bestfit index e082b1b..78682df 100644 Binary files a/examples/7-time-series-analysis/2-classic-time-series-examples/classic-time-series-examples.bestfit and b/examples/7-time-series-analysis/classic-time-series-examples.bestfit differ diff --git a/examples/7-time-series-analysis/classic-time-series-examples.bestfit.bak b/examples/7-time-series-analysis/classic-time-series-examples.bestfit.bak new file mode 100644 index 0000000..78682df Binary files /dev/null and b/examples/7-time-series-analysis/classic-time-series-examples.bestfit.bak differ diff --git a/examples/7-time-series-analysis/classic-time-series-examples.md b/examples/7-time-series-analysis/classic-time-series-examples.md new file mode 100644 index 0000000..21f4801 --- /dev/null +++ b/examples/7-time-series-analysis/classic-time-series-examples.md @@ -0,0 +1,143 @@ +# Manual Data Entry Example + +## Overview + +This example demonstrates how to enter time series data manually in RMC-BestFit by copy-pasting from CSV files. The project contains three classic datasets widely used in time series analysis textbooks and statistical software documentation. + +Manual entry is useful when your data comes from published tables, spreadsheets, or other sources not covered by the built-in download options (USGS, GHCN, CHMN, ABOM, HEC-DSS). + +## What's Inside + +### Time Series Data + +| Element | Description | +|---|---| +| `Airline Passengers` | Montly Box-Jenkins airline data from 1949--1960 on passengers (thousands) | +| `Nile River Flows` | Nile annual flow at Aswan from 1871--1970 | +| `Mauna Loa CO2` | Monthly atmospheric CO2 at Mauna Loa from 1958--2023 + + +### Time Series Analysis + +| Element | Description | +|---|---| +| `Airline Passengers - TSA` | ARIMA(1,1) fit on the airline passengers series| +| `Nile River Flows - TSA` | ARIMA(1,1) fit on the nile river flows series| +| `Mauna Loa CO2 - TSA` | ARIMA(1,1) fit on the mauna loa CO2 series| + + +## Step-by-Step Walkthrough + +### Opening the Project + +1. Open RMC-BestFit 2.0. +2. Select **File > Open** and navigate to `examples/7-time-series-analysis/`. +3. Open `classic-time-series-examples.bestfit`. + +### Exploring the Elements + +For each Time Series Analysis: + +1. Click the analysis in the Project Explorer. +2. Open the **Time Series Results** tab to view the fitted mean (and trend, if any) overlaid on the observations. +3. Open the **Residual Diagnostics** tab to view the ACF and PACF plots to confirm white-noise residuals. +4. Adjust **ForecastSteps** in the **Properties** panel under **Output** to extend the forecast horizon. + +## Analysis Settings + +Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any Time Series Analysis to inspect: + +- **Sampler type** (DEMCzs, ARWMH, HMC). +- **Iterations / Warm-up Iterations** — total post-warmup samples per chain. +- **Number of Chains** — typically 6 for routine work. +- **Thinning Interval** — keeps every Nth sample to reduce storage / autocorrelation. +- **Point Estimator** — Posterior Mean (default), Posterior Median, or Posterior Mode (MAP). +- **Credible Interval Width** — typically 0.90 or 0.95. + +## Expected Results +Below are the expected results for Time Series Analysis labeled "Airline Passengers TSA"; this should be the first analysis in the list. +Be sure to explore all of the analyses provided! + +### Parameter Estimates +The parameter estimates are found under the **MCMC Report** tab to the left as parameter summary statistics. + +| Parameter | Mean | Std Dev | 5% | Median | 95% |R-hat | ESS | +|---|---|---|---|---|---|---|---| +| Intercept (μ) | 3.69058 | 2.46234 | 0.500619 | 3.33337 | 8.21983 | 1.0009 | 384 | +| AR (φ₁) | -0.452556 | 0.167228 | -0.687214 | -0.463899 | -0.163509 | 1.0009 | 314 | +| MA (θ₁) | 0.858079 | 0.143573 | 0.603049 | 0.880236 | 1.07974 | 1.0009 | 216 | +| Scale (σ) | 24.4462 | 1.89685 | 21.6432 | 24.4837 | 27.5085 | 0.9998 | 249 | + +### Frequency / Quantile Table +While in the **Time Series Results** tab to the left, select Tabular Results to see the fitted curve values. Below are the first 30 rows of the table. + +| Date Time | 95.0% CI | 5.0% CI | Posterior Predictive | Posterior Mean | +|---|---|---|---|---| +| 1/1/1949 12:00:00 AM | 112 | 112 | 112 | 112 | +| 2/1/1949 12:00:00 AM | 155.50306848218966 | 73.96644756646296 | 114.20892346256238 | 114.64543595749552 | +| 3/1/1949 12:00:00 AM | 167.3155538869901 | 86.4070617978895 | 126.96653894287915 | 126.7680944533226 | +| 4/1/1949 12:00:00 AM | 169.72828181564307 | 87.54195370242937 | 128.6129271751446 | 128.62049223674185 | +| 5/1/1949 12:00:00 AM | 174.00565933306817 | 92.62326543872076 | 134.00042757986066 | 134.01647979442254 | +| 6/1/1949 12:00:00 AM | 166.8148882163111 | 85.59903614038397 | 126.30528188045956 | 127.73355216867266 | +| 7/1/1949 12:00:00 AM | 180.7188589828192 | 100.12349917295025 | 140.50590398518474 | 139.85464658098547 | +| 8/1/1949 12:00:00 AM | 188.94633622663878 | 107.66053261586009 | 148.1799630065681 | 149.1951055332268 | +| 9/1/1949 12:00:00 AM | 188.286054795453 | 107.84718071742975 | 148.56196298416728 | 147.4690122051194 | +| 10/1/1949 12:00:00 AM | 174.04256827220283 | 92.92159571096944 | 133.45238592584684 | 134.92252464984122 | +| 11/1/1949 12:00:00 AM | 160.48418972782565 | 79.98254706703221 | 120.85101511243971 | 119.2024986078328 | +| 12/1/1949 12:00:00 AM | 154.5728703457039 | 72.3902061857265 | 113.436934091467 | 114.8643270320847 | +| 1/1/1950 12:00:00 AM | 154.5297922662331 | 73.79194842556835 | 114.08896078149476 | 112.82175964752082 | +| 2/1/1950 12:00:00 AM | 168.4861587309925 | 87.28596071704018 | 127.57268914025985 | 129.2648577704603 | +| 3/1/1950 12:00:00 AM | 166.98502839095863 | 84.60129563854622 | 125.91325659205985 | 125.20323804458738 | +| 4/1/1950 12:00:00 AM | 184.87765809446537 | 103.64993702041437 | 143.66249927013277 | 144.61132516193476 | +| 5/1/1950 12:00:00 AM | 174.37328701862427 | 92.6152461375387 | 133.99688082787912 | 133.2067501449578 | +| 6/1/1950 12:00:00 AM | 181.77134786901934 | 101.28513325983644 | 141.09385279064193 | 141.6320593914075 | +| 7/1/1950 12:00:00 AM | 190.34999141034933 | 108.91432155353085 | 149.45009743106198 | 148.6051265153419 | +| 8/1/1950 12:00:00 AM | 216.7065362172883 | 133.93478789670115 | 175.42392077666298 | 175.69960704489537 | +| 9/1/1950 12:00:00 AM | 205.61450311163844 | 124.93514445276162 | 165.75551791788746 | 165.60379526816178 | +| 10/1/1950 12:00:00 AM | 198.03577670554847 | 116.88942294217028 | 157.13391286144875 | 156.99500664861785 | +| 11/1/1950 12:00:00 AM | 171.37175200603218 | 91.64251054433261 | 131.56194830863174 | 131.5182141253022 | +| 12/1/1950 12:00:00 AM | 171.87155032951324 | 90.68522051065791 | 131.37330028571628 | 131.17584338520726 | +| 1/1/1951 12:00:00 AM | 174.1600135056469 | 91.4742655898628 | 132.54359934277184 | 132.65016015222736 | +| 2/1/1951 12:00:00 AM | 199.46821233214465 | 116.80058477417379 | 158.82200405657542 | 158.69512727611598 | +| 3/1/1951 12:00:00 AM | 195.10582442549153 | 113.86190478015185 | 153.92314428742432 | 154.96390163214244 | +| 4/1/1951 12:00:00 AM | 214.70921713294896 | 133.87932013889747 | 174.35900825103218 | 173.01852151868164 | +| 5/1/1951 12:00:00 AM | 215.60750656364547 | 134.67773349892434 | 174.65054085798272 | 176.28497598338666 | +| 6/1/1951 12:00:00 AM | 210.6083648359847 | 128.49453053692375 | 169.62520833910395 | 168.39435301671406 | +| 7/1/1951 12:00:00 AM | 234.88506227865088 | 152.62997898803158 | 193.7027022598576 | 194.97067190188676 | +| 8/1/1951 12:00:00 AM | 231.6487515720483 | 150.21055678225923 | 190.69281753137443 | 189.79860191176218 | + +### Plots +There are plenty of plots to expore with our Time Series Analysis. Under the **Time Series Results** tab there is fitted curve plotted with the orginal data. This plot has both training and prediction estimates. + +![Time-series fit overlaid on the observations, with credible band.](./images/classic-ts-time-series.png) + +*Figure 1: Time-series fit overlaid on the observations, with credible band.* + +To take a closer look at the forecasting capability, extend the Forecast Steps in the **Properties** panel under **Options** from 0 to 50. Return the **General** section under the **Properties** panel and select **Estimate**. Then you will have the plot below. + +![Multi-step forecast extension with credible band.](./images/classic-ts-forecast.png) + +*Figure 2: Multi-step forecast extension with credible band.* + +To explore how good the fit is we can look at our residuals in the **Residual Diagnostics** tab. Investigate the ACF plot of the resodiauls to ensure residuals are not correlated. + +![Residual autocorrelation function.](./images/classic-ts-acf.png) + +*Figure 3: Residual autocorrelation function.* + +### MCMC Diagnostics + +One should always verify chain convergence before interpreting any results. There are a variety of ways including: + +- **R-hat** — should be < 1.01 for every parameter. +- **Effective Sample Size (ESS)** — at least a few hundred per parameter. +- **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). +- **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. + +These can be found under the **Markov Chain Traces** and **MCMC Reports** tabs. + +## Next Steps + +- Use the fitted ARIMA / regression model for **multi-step forecasting** with credible bands. +- Inspect residual ACF / PACF to confirm no remaining temporal structure. +- For non-stationary trend cases, project the trend function out beyond the observation window. diff --git a/examples/7-time-series-analysis/images/classic-ts-acf.png b/examples/7-time-series-analysis/images/classic-ts-acf.png new file mode 100644 index 0000000..ff6ed29 Binary files /dev/null and b/examples/7-time-series-analysis/images/classic-ts-acf.png differ diff --git a/examples/7-time-series-analysis/images/classic-ts-forecast.png b/examples/7-time-series-analysis/images/classic-ts-forecast.png new file mode 100644 index 0000000..323f439 Binary files /dev/null and b/examples/7-time-series-analysis/images/classic-ts-forecast.png differ diff --git a/examples/7-time-series-analysis/images/classic-ts-time-series.png b/examples/7-time-series-analysis/images/classic-ts-time-series.png new file mode 100644 index 0000000..fce8ac9 Binary files /dev/null and b/examples/7-time-series-analysis/images/classic-ts-time-series.png differ diff --git a/examples/7-time-series-analysis/images/manual-entry-airline-acf.png b/examples/7-time-series-analysis/images/manual-entry-airline-acf.png new file mode 100644 index 0000000..ca15b16 Binary files /dev/null and b/examples/7-time-series-analysis/images/manual-entry-airline-acf.png differ diff --git a/examples/7-time-series-analysis/images/manual-entry-airline-ts-plot.png b/examples/7-time-series-analysis/images/manual-entry-airline-ts-plot.png new file mode 100644 index 0000000..707a25a Binary files /dev/null and b/examples/7-time-series-analysis/images/manual-entry-airline-ts-plot.png differ diff --git a/examples/7-time-series-analysis/images/manual-entry-co2-ts-plot.png b/examples/7-time-series-analysis/images/manual-entry-co2-ts-plot.png new file mode 100644 index 0000000..2eae08d Binary files /dev/null and b/examples/7-time-series-analysis/images/manual-entry-co2-ts-plot.png differ diff --git a/examples/7-time-series-analysis/images/manual-entry-nile-ts-plot.png b/examples/7-time-series-analysis/images/manual-entry-nile-ts-plot.png new file mode 100644 index 0000000..637b770 Binary files /dev/null and b/examples/7-time-series-analysis/images/manual-entry-nile-ts-plot.png differ diff --git a/examples/7-time-series-analysis/images/manual-entry-project-explorer.png b/examples/7-time-series-analysis/images/manual-entry-project-explorer.png new file mode 100644 index 0000000..6355a75 Binary files /dev/null and b/examples/7-time-series-analysis/images/manual-entry-project-explorer.png differ diff --git a/examples/7-time-series-analysis/images/manual-entry-properties.png b/examples/7-time-series-analysis/images/manual-entry-properties.png new file mode 100644 index 0000000..98f32b7 Binary files /dev/null and b/examples/7-time-series-analysis/images/manual-entry-properties.png differ diff --git a/examples/7-time-series-analysis/images/synthetic-ts-acf.png b/examples/7-time-series-analysis/images/synthetic-ts-acf.png new file mode 100644 index 0000000..d34a32f Binary files /dev/null and b/examples/7-time-series-analysis/images/synthetic-ts-acf.png differ diff --git a/examples/7-time-series-analysis/images/synthetic-ts-forecast.png b/examples/7-time-series-analysis/images/synthetic-ts-forecast.png new file mode 100644 index 0000000..55f443b Binary files /dev/null and b/examples/7-time-series-analysis/images/synthetic-ts-forecast.png differ diff --git a/examples/7-time-series-analysis/images/synthetic-ts-time-series.png b/examples/7-time-series-analysis/images/synthetic-ts-time-series.png new file mode 100644 index 0000000..4c0b66b Binary files /dev/null and b/examples/7-time-series-analysis/images/synthetic-ts-time-series.png differ diff --git a/examples/7-time-series-analysis/images/ts-regression-acf.png b/examples/7-time-series-analysis/images/ts-regression-acf.png new file mode 100644 index 0000000..52f9c78 Binary files /dev/null and b/examples/7-time-series-analysis/images/ts-regression-acf.png differ diff --git a/examples/7-time-series-analysis/images/ts-regression-forecast.png b/examples/7-time-series-analysis/images/ts-regression-forecast.png new file mode 100644 index 0000000..44c0a46 Binary files /dev/null and b/examples/7-time-series-analysis/images/ts-regression-forecast.png differ diff --git a/examples/7-time-series-analysis/images/ts-regression-time-series.png b/examples/7-time-series-analysis/images/ts-regression-time-series.png new file mode 100644 index 0000000..30e5701 Binary files /dev/null and b/examples/7-time-series-analysis/images/ts-regression-time-series.png differ diff --git a/examples/7-time-series-analysis/2-classic-time-series-examples/mauna-loa-co2.csv b/examples/7-time-series-analysis/mauna-loa-co2.csv similarity index 100% rename from examples/7-time-series-analysis/2-classic-time-series-examples/mauna-loa-co2.csv rename to examples/7-time-series-analysis/mauna-loa-co2.csv diff --git a/examples/7-time-series-analysis/2-classic-time-series-examples/nile-river-flow.csv b/examples/7-time-series-analysis/nile-river-flow.csv similarity index 100% rename from examples/7-time-series-analysis/2-classic-time-series-examples/nile-river-flow.csv rename to examples/7-time-series-analysis/nile-river-flow.csv diff --git a/examples/7-time-series-analysis/1-synthetic-data-examples/synthetic-time-series-examples.bestfit b/examples/7-time-series-analysis/synthetic-time-series-examples.bestfit similarity index 99% rename from examples/7-time-series-analysis/1-synthetic-data-examples/synthetic-time-series-examples.bestfit rename to examples/7-time-series-analysis/synthetic-time-series-examples.bestfit index fce2cf8..b4dc3a5 100644 Binary files a/examples/7-time-series-analysis/1-synthetic-data-examples/synthetic-time-series-examples.bestfit and b/examples/7-time-series-analysis/synthetic-time-series-examples.bestfit differ diff --git a/examples/7-time-series-analysis/synthetic-time-series-examples.md b/examples/7-time-series-analysis/synthetic-time-series-examples.md new file mode 100644 index 0000000..8315179 --- /dev/null +++ b/examples/7-time-series-analysis/synthetic-time-series-examples.md @@ -0,0 +1,158 @@ +# synthetic-time-series-examples + +## Overview + +Synthetic time-series datasets covering trend (linear, quadratic, cubic, sinusoidal), AR / MA / ARMA processes, and a log-transformed series with linear trend. Each series has a paired Time Series Analysis fit using the corresponding model for verifying parameter recovery. + +## What's Inside + +### Time Series Data + +| Element | Description | +|---|---| +| `Intercept` | Synthetic series with constant mean only (no trend, no autocorrelation). | +| `Intercept + Linear Trend` | Synthetic series with constant mean + linear trend. | +| `Intercept + Quadratic Trend` | Synthetic series with constant mean + quadratic trend. | +| `Intercept + Cubic Trend` | Synthetic series with constant mean + cubic trend. | +| `Intercept + Sinusoidal Trend` | Synthetic series with constant mean + sinusoidal (annual cycle) trend. | +| `AR(1)` | Synthetic AR(1) series for AR-fit verification. | +| `AR(3)` | Synthetic AR(3) series for AR-fit verification. | +| `MA(1)` | Synthetic MA(1) series for MA-fit verification. | +| `MA(3)` | Synthetic MA(3) series for MA-fit verification. | +| `ARMA(1,1)` | Synthetic ARMA(1,1) series for ARMA-fit verification. | +| `ARMA(2,2)` | Synthetic ARMA(2,2) series for ARMA-fit verification. | +| `Intercept + Linear Trend + ARMA(1,1)` | Synthetic series with constant mean + linear trend + ARMA(1,1) residuals. | +| `Intercept + Linear Trend + LogTransform` | Log-normal synthetic series with constant mean + linear trend (in log space). | + +### Time Series Analysis + +| Element | Description | +|---|---| +| `Intercept` | Constant-mean fit on the intercept-only synthetic series. | +| `Intercept + Linear Trend` | Linear-trend fit on the intercept + linear trend synthetic series. | +| `Intercept + Quadratic Trend` | Quadratic-trend fit on the intercept + quadratic trend synthetic series. | +| `Intercept + Cubic Trend` | Cubic-trend fit on the intercept + cubic trend synthetic series. | +| `Intercept + Sinusoidal Trend` | Sinusoidal-trend fit on the intercept + sinusoidal trend synthetic series. | +| `AR(1)` | AR(1) fit on the AR(1) synthetic series. | +| `AR(3)` | AR(3) fit on the AR(3) synthetic series. | +| `MA(1)` | MA(1) fit on the MA(1) synthetic series. | +| `MA(3)` | MA(3) fit on the MA(3) synthetic series. | +| `ARMA(1,1)` | ARMA(1,1) fit on the ARMA(1,1) synthetic series. | +| `ARMA(2,2)` | ARMA(2,2) fit on the ARMA(2,2) synthetic series. | +| `Intercept + Linear Trend + ARMA(1,1)` | Linear-trend + ARMA(1,1) fit on the corresponding synthetic series. | +| `Intercept + Linear Trend + LogTransform` | Linear-trend fit with logarithmic transform on the log-normal synthetic series. | + +## Step-by-Step Walkthrough + +### Opening the Project + +1. Open RMC-BestFit 2.0. +2. Select **File > Open** and navigate to `examples/7-time-series-analysis/`. +3. Open `synthetic-time-series-examples.bestfit`. + +### Exploring the Elements + +For each Time Series Analysis: + +1. Click the analysis in the Project Explorer. +2. Open the **Time Series Results** tab to view the fitted mean (and trend, if any) overlaid on the observations. +3. Open the **Residual Diagnostics** tab to view the ACF and PACF plots to confirm white-noise residuals. +4. Adjust **ForecastSteps** in the **Properties** panel under **Output** to extend the forecast horizon. + +## Analysis Settings + +Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any Time Series Analysis to inspect: + +- **Sampler type** (DEMCzs, ARWMH, HMC). +- **Iterations / Warm-up Iterations** — total post-warmup samples per chain. +- **Number of Chains** — typically 6 for routine work. +- **Thinning Interval** — keeps every Nth sample to reduce storage / autocorrelation. +- **Point Estimator** — Posterior Mean (default), Posterior Median, or Posterior Mode (MAP). +- **Credible Interval Width** — typically 0.90 or 0.95. + +## Expected Results + +Below are the expected results for Time Series Analysis labeled "Intercept + Linear Trend + Log Transform"; this should be the last analysis in the list. + +### Parameter Estimates +The parameter estimates are found under the **MCMC Report** tab to the left as parameter summary statistics. + +| Parameter | Mean | Std Dev | 5% | Median | 95% |R-hat | ESS | +|---|---|---|---|---|---|---|---| +| Intercept (μ) | 5.53757 | 0.0409761 | 5.47053 | 5.53781 | 5.604 | 1.0003 | 9423 | +| Trend (γ) | 0.00427976 | 0.000257608 | 0.00386032 | 0.00427742 | 0.00470331 | 1.0001 | 9196 | +| AR (φ₁) | 0.11329 | 0.0612233 | 0.0123687 | 0.113767 | 0.214336 | 1.0001 | 9697 +| Scale (σ) | 0.29827 | 0.0129644 | 0.27796 | 0.29771 | 0.320289 | 0.9998 | 9685 | + +### Frequency / Quantile Table + +While in the **Time Series Results** tab to the left, select Tabular Results to see the fitted curve values. Below are the first 30 rows of the table. + +| Date Time | 95.0% CI | 5.0% CI | Posterior Predictive | Posterior Mean | +|---|---|---|---|---| +| 1/1/1949 12:00:00 AM | 311.1262212999999 | 311.1262212999999 | 311.12622129999977 | 311.1262212999999 | +| 2/1/1949 12:00:00 AM | 426.38464243991456 | 160.3555921591378 | 272.0425283311215 | 261.07351155331224 | +| 3/1/1949 12:00:00 AM | 424.46463843643573 | 159.78470682677477 | 272.05012904582776 | 260.1809812803675 | +| 4/1/1949 12:00:00 AM | 408.09905232176817 | 149.53386083791813 | 259.37705714461174 | 246.7396378165508 | +| 5/1/1949 12:00:00 AM | 396.74411649177745 | 144.81776614190844 | 252.6907621135749 | 242.57371338100327 | +| 6/1/1949 12:00:00 AM | 396.6717315365566 | 149.0295381566797 | 254.6866736022618 | 245.6132172532968 | +| 7/1/1949 12:00:00 AM | 396.42334323013915 | 144.42669990469437 | 250.69056059650183 | 239.76224554610238 | +| 8/1/1949 12:00:00 AM | 408.15110411277294 | 150.75550115659718 | 259.921034851638 | 248.6528737304171 | +| 9/1/1949 12:00:00 AM | 431.6953604031021 | 162.5216750224946 | 277.73055391516914 | 265.3167659703401 | +| 10/1/1949 12:00:00 AM | 422.2882684019153 | 159.22809898768745 | 270.71372007551656 | 259.72340060092654 | +| 11/1/1949 12:00:00 AM | 425.0935435021051 | 159.26175778459083 | 273.6257775227426 | 260.18537784606764 | +| 12/1/1949 12:00:00 AM | 428.7147369359031 | 160.03328228417746 | 274.87256104088107 | 262.8825257942729 | +| 1/1/1950 12:00:00 AM | 454.4713225381115 | 169.52176302248955 | 290.2837588253908 | 277.6621283546742 | +| 2/1/1950 12:00:00 AM | 458.8741473682888 | 171.15143412370028 | 291.6433470960421 | 279.91563488419644 | +| 3/1/1950 12:00:00 AM | 434.8795473977411 | 159.42046280463182 | 274.5706411675759 | 263.66323816329697 | +| 4/1/1950 12:00:00 AM | 442.25990380720634 | 165.65909639222818 | 282.02708147970344 | 269.37437844475056 | +| 5/1/1950 12:00:00 AM | 456.4208373564537 | 169.90426837409942 | 293.6239203764719 | 280.37356142140203 | +| 6/1/1950 12:00:00 AM | 446.65474650129084 | 170.14862426258497 | 287.7248740111439 | 274.53573923036726 | +| 7/1/1950 12:00:00 AM | 436.4575038508696 | 163.4009833210243 | 279.6854102247972 | 266.6976049750208 | +| 8/1/1950 12:00:00 AM | 451.5285842271729 | 166.2191849539441 | 287.70950738330174 | 274.5751230752903 | +| 9/1/1950 12:00:00 AM | 430.19811532556855 | 160.04761583425363 | 275.00720195183146 | 262.9709853667392 | +| 10/1/1950 12:00:00 AM | 459.5385834118447 | 171.29575959941116 | 293.35090864505696 | 279.77194133062585 | +| 11/1/1950 12:00:00 AM | 467.3321026246339 | 176.3202710465978 | 300.7631729495565 | 286.61580982215463 | +| 12/1/1950 12:00:00 AM | 482.50679130310374 | 179.2213266660087 | 306.81538938156194 | 293.1780208489188 | +| 1/1/1951 12:00:00 AM | 430.2026466981867 | 156.92773038740907 | 272.7678859179577 | 259.7902523004257 | +| 2/1/1951 12:00:00 AM | 420.9960530686117 | 154.05294848574997 | 267.8076579331828 | 256.9565662891865 | +| 3/1/1951 12:00:00 AM | 449.61993592388905 | 168.32485956852798 | 286.8877555915513 | 274.8526537046771 | +| 4/1/1951 12:00:00 AM | 442.0588094852041 | 165.3943326617061 | 282.4482399656593 | 269.6852167466676 | +| 5/1/1951 12:00:00 AM | 458.7570112533463 | 172.6486259588133 | 292.413840099478 | 280.2161015012757 | +| 6/1/1951 12:00:00 AM | 458.1496690960134 | 168.41337129539116 | 291.45188954186347 | 278.9453763667788 | + +### Plots +There are plenty of plots to expore with our Time Series Analysis. Under the **Time Series Results** tab there is fitted curve plotted with the orginal data. This plot has both training and prediction estimates. + +![Time-series fit overlaid on the observations, with credible band.](./images/synthetic-ts-time-series.png) + +*Figure 1: Time-series fit overlaid on the observations, with credible band.* + +To take a closer look at the forecasting capability, extend the Forecast Steps in the **Properties** panel under **Options** from 0 to 100. Return the **General** section under the **Properties** panel and select **Estimate**. Then you will have the plot below. + +![Multi-step forecast extension with credible band.](./images/synthetic-ts-forecast.png) + +*Figure 2: Multi-step forecast extension with credible band.* + +To explore how good the fit is we can look at our residuals in the **Residual Diagnostics** tab. Investigate the ACF plot of the resodiauls to ensure residuals are not correlated. + +![Residual autocorrelation function.](./images/synthetic-ts-acf.png) + +*Figure 3: Residual autocorrelation function.* + +### MCMC Diagnostics + +One should always verify chain convergence before interpreting any results. There are a variety of ways including: + +- **R-hat** — should be < 1.01 for every parameter. +- **Effective Sample Size (ESS)** — at least a few hundred per parameter. +- **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). +- **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. + +These can be found under the **Markov Chain Traces** and **MCMC Reports** tabs. + +## Next Steps + +- Use the fitted ARIMA / regression model for **multi-step forecasting** with credible bands. +- Inspect residual ACF / PACF to confirm no remaining temporal structure. +- For non-stationary trend cases, project the trend function out beyond the observation window. diff --git a/examples/7-time-series-analysis/3-time-series-regression-example/time-series-regression-example.bestfit b/examples/7-time-series-analysis/time-series-regression-example.bestfit similarity index 99% rename from examples/7-time-series-analysis/3-time-series-regression-example/time-series-regression-example.bestfit rename to examples/7-time-series-analysis/time-series-regression-example.bestfit index bff8f9d..3094610 100644 Binary files a/examples/7-time-series-analysis/3-time-series-regression-example/time-series-regression-example.bestfit and b/examples/7-time-series-analysis/time-series-regression-example.bestfit differ diff --git a/examples/7-time-series-analysis/time-series-regression-example.md b/examples/7-time-series-analysis/time-series-regression-example.md new file mode 100644 index 0000000..f6a32d4 --- /dev/null +++ b/examples/7-time-series-analysis/time-series-regression-example.md @@ -0,0 +1,140 @@ +# time-series-regression-example + +## Overview + +Multivariate time-series regression on classic US macroeconomic indicators (consumption, income, production, savings, unemployment). Demonstrates simple and multiple linear regression with autocorrelated residuals. + +## What's Inside + +### Time Series Data + +| Element | Description | +|---|---| +| `Consumption` | Quarterly US personal consumption expenditures (response variable for the regression examples). | +| `Income` | Quarterly US personal disposable income (regressor). | +| `Production` | Quarterly US industrial production index (regressor). | +| `Savings` | Quarterly US personal savings rate (regressor). | +| `Unemployment` | Quarterly US unemployment rate (regressor). | + +### Time Series Analysis + +| Element | Description | +|---|---| +| `Simple Linear Regression` | Simple linear regression of consumption on income, with autocorrelated residuals modeled as ARMA. | +| `Multiple Linear Regression` | Multiple linear regression of consumption on income, production, savings, and unemployment, with autocorrelated residuals modeled as ARMA. | + +## Step-by-Step Walkthrough + +### Opening the Project + +1. Open RMC-BestFit 2.0. +2. Select **File > Open** and navigate to `examples/7-time-series-analysis/`. +3. Open `time-series-regression-example.bestfit`. + +### Exploring the Elements + +For each Time Series Analysis: + +1. Click the analysis in the Project Explorer. +2. Open the **Time Series Results** tab to view the fitted mean (and trend, if any) overlaid on the observations. +3. Open the **Residual Diagnostics** tab to view the ACF and PACF plots to confirm white-noise residuals. +4. Adjust **ForecastSteps** in the **Properties** panel under **Output** to extend the forecast horizon. + + +## Analysis Settings + +Each Bayesian analysis in this project uses the DEMCzs sampler with project-specific iteration / warm-up settings. Open the **Properties** panel of any Time Series Analysis to inspect: + +- **Sampler type** (DEMCzs, ARWMH, HMC). +- **Iterations / Warm-up Iterations** — total post-warmup samples per chain. +- **Number of Chains** — typically 6 for routine work. +- **Thinning Interval** — keeps every Nth sample to reduce storage / autocorrelation. +- **Point Estimator** — Posterior Mean (default), Posterior Median, or Posterior Mode (MAP). +- **Credible Interval Width** — typically 0.90 or 0.95. + +## Expected Results +Below are the expected results for Time Series Analysis labeled "Simple Linear Regression"; this should be the first analysis in the list. +Be sure to explore all of the analyses provided! + +### Parameter Estimates +The parameter estimates are found under the **MCMC Report** tab to the left as parameter summary statistics. + +| Parameter | Mean | Std Dev | 5% | Median | 95% |R-hat | ESS | +|---|---|---|---|---|---|---|---| +| Intercept (μ) | 0.581308 | 0.06669 | 0.472763 | 0.581872 | 0.692189 | 1.0003 | 9747 | +| Covariate (β₁) | 0.32473 | 0.0574467 | 0.230149 | 0.324924 | 0.416953 | 1.0000 | 9422 | +| Scale (σ) | 0.604545 | 0.0350395 | 0.5497 | 0.603117 | 0.66489 | 1.0000 | 9446 | + + +### Frequency / Quantile Table +While in the **Time Series Results** tab to the left, select Tabular Results to see the fitted curve values. Below are the first 30 rows of the table. + +| Date Time | 95.0% CI | 5.0% CI | Posterior Predictive | Posterior Mean | +|---|---|---|---|---| +| 1/1/1970 12:00:00 AM | 1.8947967439767812 | -0.08878776398652398 | 0.8887434844939699 | 0.897030287594515 | +| 4/1/1970 12:00:00 AM | 1.959509460950857 | -0.035207498646478416 | 0.9615312807695431 | 0.9609447677632177 | +| 7/1/1970 12:00:00 AM | 2.103883210152694 | 0.08210326467655665 | 1.0935854275675025 | 1.0857012889939535 | +| 10/1/1970 12:00:00 AM | 1.4912828064776469 | -0.5410753358916635 | 0.4880024850919481 | 0.4984138181279866 | +| 1/1/1971 12:00:00 AM | 2.197477919467802 | 0.21177767713762502 | 1.2087580214909495 | 1.226595979674443 | +| 4/1/1971 12:00:00 AM | 2.0481764325470753 | 0.045591224947840264 | 1.0476641494475256 | 1.0513006078429146 | +| 7/1/1971 12:00:00 AM | 1.7439809007184266 | -0.2492498112689949 | 0.7522165843167626 | 0.7540034124420042 | +| 10/1/1971 12:00:00 AM | 1.9501939864959803 | -0.04002912542873376 | 0.9601734488165874 | 0.9580353266927637 | +| 1/1/1972 12:00:00 AM | 1.7083225077155817 | -0.25621023137652815 | 0.7228842059184816 | 0.729713496717202 | +| 4/1/1972 12:00:00 AM | 1.9034111649832308 | -0.07737956769735911 | 0.9218215912295864 | 0.9114363881820144 | +| 7/1/1972 12:00:00 AM | 2.192788616849879 | 0.17910740905670403 | 1.1982901584014605 | 1.1996264145523563 | +| 10/1/1972 12:00:00 AM | 2.8733959666254334 | 0.8049833282255875 | 1.841359241946771 | 1.8445905659909538 | +| 1/1/1973 12:00:00 AM | 1.811933586944315 | -0.17824681496894523 | 0.8040869552646184 | 0.8112989448623736 | +| 4/1/1973 12:00:00 AM | 1.8354761535350508 | -0.18895806036359272 | 0.8271318730889791 | 0.8392441633957352 | +| 7/1/1973 12:00:00 AM | 1.7264599592271277 | -0.2622279819682317 | 0.7232152818125525 | 0.722181967793024 | +| 10/1/1973 12:00:00 AM | 1.9238596595936186 | -0.07167677726105205 | 0.9372133166245797 | 0.9365007678304581 | +| 1/1/1974 12:00:00 AM | 1.0529754866217218 | -0.975922390456731 | 0.045869642911720965 | 0.04171003123914929 | +| 4/1/1974 12:00:00 AM | 1.2837895246284106 | -0.7349352587644401 | 0.28244658832559466 | 0.2765972350692004 | +| 7/1/1974 12:00:00 AM | 1.6078955836694329 | -0.40652708731113396 | 0.6139470689246684 | 0.6119913076316229 | +| 10/1/1974 12:00:00 AM | 1.5306087639646597 | -0.45460877399805993 | 0.5421552205214099 | 0.5414977727492499 | +| 1/1/1975 12:00:00 AM | 1.5339752553006398 | -0.45026544187014966 | 0.5327265584878059 | 0.5281515571909432 | +| 4/1/1975 12:00:00 AM | 3.1044046405555696 | 0.9877488499845604 | 2.0617173608233292 | 2.0544473796226073 | +| 7/1/1975 12:00:00 AM | 1.122666115653703 | -0.9046251667002961 | 0.10742333564655293 | 0.10598035662758598 | +| 10/1/1975 12:00:00 AM | 1.8345530439272693 | -0.1819291098935081 | 0.8328262644184481 | 0.8286430302545305 | +| 1/1/1976 12:00:00 AM | 1.9423207482175358 | -0.06113694111504899 | 0.9499031945955801 | 0.960676180641524 | +| 4/1/1976 12:00:00 AM | 1.7442966055329143 | -0.24294762657036303 | 0.7454331590098825 | 0.7492906535818611 | +| 7/1/1976 12:00:00 AM | 1.8026756871512377 | -0.15350308094661344 | 0.8224136870951197 | 0.8195625345155143 | +| 10/1/1976 12:00:00 AM | 1.7722238818252865 | -0.22678748322095407 | 0.7695961146030798 | 0.7743871652268851 | +| 1/1/1977 12:00:00 AM | 1.5819214817338088 | -0.42724202225557156 | 0.5683582070140585 | 0.5712157162941516 | +| 4/1/1977 12:00:00 AM | 2.006543903320349 | -0.02295309101369193 | 0.9826707951014787 | 0.9833526804624401 | +| 7/1/1977 12:00:00 AM | 2.07848769800467 | 0.08160724804220226 | 1.074194940119109 | 1.0745086316117098 | + +### Plots +There are plenty of plots to expore with our Time Series Analysis. Under the **Time Series Results** tab there is fitted curve plotted with the orginal data. This plot has both training and prediction estimates. + +![Time-series fit overlaid on the observations, with credible band.](./images/ts-regression-time-series.png) + +*Figure 1: Time-series fit overlaid on the observations, with credible band.* + +To take a closer look at the forecasting capability, extend the Forecast Steps in the **Properties** panel under **Options** from 0 to 50. Return the **General** section under the **Properties** panel and select **Estimate**. Then you will have the plot below. + +![Multi-step forecast extension with credible band.](./images/ts-regression-forecast.png) + +*Figure 2: Multi-step forecast extension with credible band.* + +To explore how good the fit is we can look at our residuals in the **Residual Diagnostics** tab. Investigate the ACF plot of the resodiauls to ensure residuals are not correlated. + +![Residual autocorrelation function.](./images/ts-regression-acf.png) + +*Figure 3: Residual autocorrelation function.* + +### MCMC Diagnostics + +One should always verify chain convergence before interpreting any results. There are a variety of ways including: + +- **R-hat** — should be < 1.01 for every parameter. +- **Effective Sample Size (ESS)** — at least a few hundred per parameter. +- **Trace plots** — should look like fuzzy, well-mixed caterpillars (no drift, no sticking). +- **Posterior** — overall posterior log-likelihood should be visually stationary in the mean-likelihood plot. + +These can be found under the **Markov Chain Traces** and **MCMC Reports** tabs. + +## Next Steps + +- Use the fitted ARIMA / regression model for **multi-step forecasting** with credible bands. +- Inspect residual ACF / PACF to confirm no remaining temporal structure. +- For non-stationary trend cases, project the trend function out beyond the observation window. \ No newline at end of file diff --git a/examples/README.md b/examples/README.md index 86ca16a..4b83515 100644 --- a/examples/README.md +++ b/examples/README.md @@ -18,10 +18,6 @@ This folder contains tutorial example projects for RMC-BestFit 2.0. Each `.bestf (Chapter 3 is reserved for distribution-fitting workflows already covered inline within chapter 4.) -## Project Naming Convention - -All projects follow **lowercase kebab-case**: `example-name.bestfit`. ASCII only, hyphens between words, no spaces, no commas, no Title Case. Where two projects in different sub-folders solve the same problem with different methods (Bayesian vs. Bulletin 17C, etc.), suffixes such as `-bayesian` and `-b17c` disambiguate. - ## How to Open an Example 1. Open RMC-BestFit 2.0. @@ -31,23 +27,6 @@ All projects follow **lowercase kebab-case**: `example-name.bestfit`. ASCII only 5. Click any element to view its plots and properties. 6. Open the matching `.md` tutorial in the same folder for a step-by-step guide. -## Screenshot Conventions - -Tutorial markdown files reference screenshots in `images/` subfolders next to each example. To populate them: - -1. Create an `images/` folder in the example's directory. -2. Capture screenshots from RMC-BestFit matching the alt-text descriptions. -3. Save as PNG with the filename specified in each image reference. -4. Naming convention: `-.png`. - -## Filling in Output Tables - -The analysis-tutorial markdowns (chapters 4-7) include placeholder tables for parameter estimates, AEP / quantile values, and MCMC diagnostics. These are intentionally empty so users can paste in real values from their own re-runs: - -- **Parameter table** — right-click an analysis alternative > **Open MCMC Report** > copy the parameter section. -- **Frequency / AEP table** — right-click the Frequency chart > **Copy Table**. -- **R-hat / ESS values** — copy from the MCMC Report or from the Properties panel under MCMC Diagnostics. - ## Verification Status The `synthetic-*` projects under chapters 6 and 7 are **verification fixtures** — they contain synthetic data generated from known parameters, and the corresponding fits should recover the ground truth within MCMC sampling noise. They are useful both as tutorials and as smoke tests when validating new builds.