Historical AORC Event Diagnostic Comparison with USGS Stage¶
This notebook executes one archived 24–26 December 2020 AORC rain-on-grid event on the Bald Eagle Creek RasExamples model, verifies the forcing from the source NetCDF through temporary and completed plan HDFs, inspects hydraulic and runtime results, and compares the event plan's nearest-cell water surface with observed USGS stage.
Important interpretation boundary¶
The AORC forcing and the HEC-RAS run are fully qualified here. The USGS plot is a diagnostic comparison, not a calibration validation: the example retains the template model's synthetic boundary hydrographs, initial conditions, and gate/control histories because no reviewed historical operations dataset is bundled with the fixture. It would be misleading to score model skill without first replacing and documenting those inputs.
Manual review remains required for the AORC product, units/timing, terrain and forcing coverage, all HEC-RAS runtime/BCO messages, mass balance, convergence, hydraulic plausibility, gauge datum, gauge-to-cell location, and historical boundary/operations data.
# Development mode: import repository source when run from a clone.
USE_LOCAL_SOURCE = True
import sys
from pathlib import Path
repo_root = Path.cwd().parent if Path.cwd().name.lower() == "examples" else Path.cwd()
if USE_LOCAL_SOURCE and str(repo_root) not in sys.path:
sys.path.insert(0, str(repo_root))
import ras_commander
print(f"ras-commander {ras_commander.__version__} ({'repository source' if USE_LOCAL_SOURCE else 'installed package'})")
ras-commander 0.105.0 (repository source)
from datetime import timedelta
import logging
import os
from pathlib import Path
import re
import warnings
import geopandas as gpd
import h5py
import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
from shapely.geometry import Point
import xarray as xr
from ras_commander import (
HdfMesh,
HdfProject,
HdfResultsMesh,
HdfResultsPlan,
RasCmdr,
RasExamples,
RasPlan,
RasPreprocess,
RasUnsteady,
get_ras_exe,
init_ras_project,
)
from ras_commander.precip import PrecipAorc
from ras_commander.usgs import get_gauge_metadata, retrieve_stage_data
ipython = get_ipython()
if ipython is not None:
ipython.run_line_magic("matplotlib", "inline")
for logger_name in ("httpx", "rasterio", "ras_commander"):
logging.getLogger(logger_name).setLevel(logging.WARNING)
run_root = Path(os.environ.get(
"RAS_COMMANDER_EXAMPLE_RUN_ROOT",
repo_root / "working" / "example_914_historical_aorc_diagnostic",
)).resolve()
run_root.mkdir(parents=True, exist_ok=True)
def rel(path: Path) -> str:
path = Path(path).resolve()
try:
return path.relative_to(repo_root.resolve()).as_posix()
except ValueError:
return path.name
RAS_VERSION = "7.0"
MESH_NAME = "BaldEagleCr"
TEMPLATE_PLAN = "06"
TEMPLATE_UNSTEADY = "03"
TEMPLATE_GEOMETRY = "09"
SIM_START = pd.Timestamp("2020-12-24 00:00")
SIM_END = pd.Timestamp("2020-12-26 00:00")
FIRST_VALID_TIME = SIM_START + pd.Timedelta(hours=1)
EXPECTED_FRAMES = int((SIM_END - SIM_START).total_seconds() / 3600)
VALIDATION_GAUGE = "01548005"
AORC_RESOLUTION_METERS = 2000.0
ras_exe = get_ras_exe(RAS_VERSION)
print(f"Configured HEC-RAS {RAS_VERSION}; mesh {MESH_NAME}; {EXPECTED_FRAMES} hourly AORC intervals.")
Configured HEC-RAS 7.0; mesh BaldEagleCr; 48 hourly AORC intervals.
Extract the model and locate the diagnostic gauge¶
The AORC footprint uses a 50-percent WGS84 buffer around the geometry. Gauge metadata is fetched from USGS and projected into the model CRS for a transparent nearest-cell distance check.
project_path = RasExamples.extract_project(
"BaldEagleCrkMulti2D",
output_path=run_root / "model",
suffix="historical_aorc_diagnostic",
)
ras = init_ras_project(
project_path, ras_version=RAS_VERSION,
load_results_summary=False, hide_intro=True,
)
geometry_hdf = ras.project_folder / f"{ras.project_name}.g{TEMPLATE_GEOMETRY}.hdf"
mesh_areas = HdfMesh.get_mesh_areas(geometry_hdf)
# Physical cells only, matching the ghost-free cell results read later.
mesh_points = HdfMesh.get_mesh_cell_points(geometry_hdf, include_ghost_cells=False)
mesh_points = mesh_points.loc[mesh_points["mesh_name"] == MESH_NAME].sort_values("cell_id").reset_index(drop=True)
mesh_polygons = HdfMesh.get_mesh_cell_polygons(geometry_hdf)
mesh_attributes = HdfMesh.get_mesh_area_attributes(geometry_hdf)
mesh_cell_count = int(np.asarray(mesh_attributes.loc["Cell Count", "Value"]).reshape(-1)[0])
BOUNDS = tuple(float(value) for value in HdfProject.get_project_bounds_latlon(
geometry_hdf, buffer_percent=50.0
))
gauge_meta = get_gauge_metadata(VALIDATION_GAUGE)
required_meta = {"latitude", "longitude", "gage_datum_ft"}
missing_meta = required_meta.difference(gauge_meta)
if missing_meta:
raise RuntimeError(f"USGS gauge metadata is missing {sorted(missing_meta)}")
gauge_wgs84 = gpd.GeoDataFrame(
[{"site_id": VALIDATION_GAUGE, "name": gauge_meta["station_name"]}],
geometry=[Point(float(gauge_meta["longitude"]), float(gauge_meta["latitude"]))],
crs="EPSG:4326",
)
gauge_model = gauge_wgs84.to_crs(mesh_points.crs)
display(pd.DataFrame([{
"model": ras.project_name,
"active computational cells": mesh_cell_count,
"result-center slots": len(mesh_points),
"AORC WGS84 bounds": BOUNDS,
"USGS gauge": VALIDATION_GAUGE,
"station": gauge_meta["station_name"],
"gage datum (ft)": float(gauge_meta["gage_datum_ft"]),
}]).T.rename(columns={0: "value"}))
fig, ax = plt.subplots(figsize=(11, 5.5), constrained_layout=True)
mesh_areas.boundary.plot(ax=ax, color="#263238", linewidth=1.2, label="2D flow area")
gauge_model.plot(ax=ax, color="#d95f02", edgecolor="black", marker="^", markersize=100, label="USGS stage gauge")
ax.set(title="Bald Eagle Creek Model and Diagnostic USGS Gauge", xlabel="Easting (ft)", ylabel="Northing (ft)")
ax.set_aspect("equal")
ax.legend(loc="best")
plt.show()
| value | |
|---|---|
| model | BaldEagleDamBrk |
| active computational cells | 18066 |
| result-center slots | 18066 |
| AORC WGS84 bounds | (-77.86715797330825, 40.9043529357912, -77.219... |
| USGS gauge | 01548005 |
| station | Bald Eagle Creek near Beech Creek Station, PA |
| gage datum (ft) | 559.25 |

Download and inspect the archived AORC forcing¶
AORC frames are hourly interval amounts with interval-ending timestamps. The first requested frame therefore ends one hour after the plan start. The exact source array and metadata are inspected before authoring the model.
precipitation_dir = ras.project_folder / "Precipitation"
precipitation_dir.mkdir(exist_ok=True)
aorc_file = precipitation_dir / "aorc_20201224_20201226.nc"
PrecipAorc.download(
bounds=BOUNDS,
start_time=FIRST_VALID_TIME,
end_time=SIM_END,
output_path=aorc_file,
target_crs="EPSG:5070",
resolution=AORC_RESOLUTION_METERS,
)
assert aorc_file.is_file() and aorc_file.stat().st_size > 0
with xr.open_dataset(aorc_file) as dataset:
forcing = dataset.load()
source_amount_mm = forcing["APCP_surface"]
forcing_times = pd.DatetimeIndex(pd.to_datetime(source_amount_mm["time"].values))
assert len(forcing_times) == EXPECTED_FRAMES
assert forcing_times[0] == FIRST_VALID_TIME and forcing_times[-1] == SIM_END
assert source_amount_mm.attrs["value_type"] == "amount"
assert float(source_amount_mm.attrs["accumulation_interval_hours"]) == 1.0
assert float(np.nanmin(source_amount_mm.values)) >= 0.0
source_total_mm = source_amount_mm.sum("time", min_count=1)
source_valid_mask = np.isfinite(source_total_mm.values).reshape(-1)
assert float(np.nanmax(source_total_mm.values)) > 0.0
spatial_mean_in = source_amount_mm.mean(dim=("x", "y")) / 25.4
source_cumulative_mean_in = spatial_mean_in.cumsum("time")
display(pd.DataFrame([{
"first interval end": forcing_times[0],
"last interval end": forcing_times[-1],
"frames": len(forcing_times),
"spatial-mean event depth (in)": float(source_cumulative_mean_in[-1]),
"maximum-grid event depth (in)": float(np.nanmax(source_total_mm.values) / 25.4),
"NetCDF": f"Precipitation/{aorc_file.name}",
}]))
fig, (ax_series, ax_map) = plt.subplots(1, 2, figsize=(14, 5), constrained_layout=True)
ax_series.bar(forcing_times, spatial_mean_in, width=pd.Timedelta(minutes=45), color="#2b6f9f")
ax_series.set(title="Archived AORC Hourly Precipitation", xlabel="Interval end", ylabel="Spatial-mean depth (in)")
ax_series.tick_params(axis="x", rotation=30)
ax_series.grid(axis="y", alpha=0.25)
image = (source_total_mm / 25.4).plot.pcolormesh(
ax=ax_map, x="x", y="y", cmap="Blues", add_colorbar=False
)
ax_map.set(title="48-Hour AORC Accumulation", xlabel="SHG easting (m)", ylabel="SHG northing (m)")
fig.colorbar(image, ax=ax_map, label="Cumulative depth (in)")
plt.show()
| first interval end | last interval end | frames | spatial-mean event depth (in) | maximum-grid event depth (in) | NetCDF | |
|---|---|---|---|---|---|---|
| 0 | 2020-12-24 01:00:00 | 2020-12-26 | 48 | 2.742425 | 3.409449 | Precipitation/aorc_20201224_20201226.nc |

Author the isolated historical-event plan¶
The template plan and unsteady file are cloned. Only precipitation and the plan window are changed; template hydraulic boundaries and controls are retained and are the reason the later USGS comparison is diagnostic only. The gridded setter also completes the required evapotranspiration, air-density, and air-pressure modes without overriding an explicit nonblank choice; runtime-message and HDF review below remains required.
event_unsteady = RasPlan.clone_unsteady(
TEMPLATE_UNSTEADY, new_title="AORC Dec 2020 Diagnostic", ras_object=ras
)
event_plan = RasPlan.clone_plan(
TEMPLATE_PLAN, new_plan_shortid="AORC 2020", new_title="AORC Dec 2020 Diagnostic",
geometry=TEMPLATE_GEOMETRY, unsteady_flow=event_unsteady, num_cores=4,
intervals={"computation": "5SEC", "output": "10MIN", "mapping": "10MIN"},
ras_object=ras,
)
RasPlan.update_simulation_date(
event_plan, SIM_START.to_pydatetime(), SIM_END.to_pydatetime(), ras_object=ras
)
RasUnsteady.set_gridded_precipitation(
unsteady_file=event_unsteady,
netcdf_path=Path("Precipitation") / aorc_file.name,
dataset_name="APCP_surface",
units="mm",
value_type="amount",
first_timestep_hours=1.0,
interpolation="Bilinear",
historic=True,
ras_object=ras,
)
config = RasUnsteady.get_met_precipitation_config(event_unsteady, ras_object=ras)
assert config["mode"] == "Gridded" and config["source"] == "GDAL Raster File(s)"
unsteady_hdf = ras.project_folder / f"{ras.project_name}.u{event_unsteady}.hdf"
imported_path = "Event Conditions/Meteorology/Precipitation/Imported Raster Data/Values"
with h5py.File(unsteady_hdf, "r") as hdf:
imported_cumulative = hdf[imported_path][:]
assert imported_cumulative.shape[0] == EXPECTED_FRAMES + 1
assert np.allclose(imported_cumulative[0], 0.0)
assert float(np.nanmin(np.diff(imported_cumulative, axis=0))) >= -1e-7
display(pd.Series({
"plan": f"p{event_plan}",
"unsteady flow": f"u{event_unsteady}",
"simulation start": SIM_START,
"simulation end": SIM_END,
"forcing": f"Precipitation/{aorc_file.name}",
"imported cumulative frames": imported_cumulative.shape[0],
"template boundaries/controls retained": True,
}, name="historical event setup").to_frame())
| historical event setup | |
|---|---|
| plan | p07 |
| unsteady flow | u04 |
| simulation start | 2020-12-24 00:00:00 |
| simulation end | 2020-12-26 00:00:00 |
| forcing | Precipitation/aorc_20201224_20201226.nc |
| imported cumulative frames | 49 |
| template boundaries/controls retained | True |
Gold-standard temporary-HDF forcing check¶
Preprocessing proves what the solver will receive. The zero datum plus 48 hourly interval amounts are integrated and compared with the source NetCDF.
prepared = RasPreprocess.preprocess_plan(event_plan, ras_object=ras, max_wait=600)
if not bool(prepared):
raise RuntimeError(prepared.error)
with h5py.File(prepared.tmp_hdf_path, "r") as hdf:
solver_values = hdf["Event Conditions/Meteorology/Precipitation/Values"][:]
solver_timestamps = hdf["Event Conditions/Meteorology/Precipitation/Timestamp"][:]
assert solver_values.shape[0] == EXPECTED_FRAMES + 1
assert len(solver_timestamps) == solver_values.shape[0]
assert np.allclose(solver_values[0], 0.0)
assert float(np.nanmin(solver_values)) >= 0.0
solver_total = np.sum(solver_values, axis=0)
# HEC-RAS preserves the NetCDF row-major ordering for this GDAL-authored grid.
# Compare the exact solver array rather than relying on a plotted orientation.
source_flat_in = source_total_mm.fillna(0.0).values.reshape(-1) / 25.4
assert solver_total.size == source_flat_in.size
precompute_error = solver_total - source_flat_in
assert float(np.nanmax(np.abs(precompute_error))) <= 5e-6
solver_time = pd.date_range(SIM_START, SIM_END, periods=solver_values.shape[0])
solver_cumulative = np.cumsum(solver_values, axis=0)
fig, ax = plt.subplots(figsize=(11, 4.4))
ax.plot(solver_time, np.nanmean(solver_cumulative[:, source_valid_mask], axis=1), color="#2b6f9f", label="Valid-pixel mean")
ax.plot(solver_time, np.nanmax(solver_cumulative, axis=1), color="#b5453c", label="Raster maximum")
ax.set(title="Temporary-HDF Cumulative AORC Precipitation", xlabel="Model time", ylabel="Cumulative depth (in)")
ax.grid(alpha=0.25)
ax.legend()
fig.autofmt_xdate()
plt.show()
display(pd.DataFrame([{
"temporary-HDF rows": solver_values.shape[0],
"raster positions": solver_values.shape[1],
"valid precipitation positions": int(source_valid_mask.sum()),
"final valid-pixel mean depth (in)": float(np.nanmean(solver_total[source_valid_mask])),
"maximum source-to-precompute error (in)": float(np.nanmax(np.abs(precompute_error))),
}]).round(7))

| temporary-HDF rows | raster positions | valid precipitation positions | final valid-pixel mean depth (in) | maximum source-to-precompute error (in) | |
|---|---|---|---|---|---|
| 0 | 49 | 720 | 500 | 2.742427 | 0.000003 |
Compute and verify the completed event plan¶
Final-HDF precipitation is compared with source AORC values at active mesh centers. Runtime, BCO, mass-balance, convergence, and hydraulic results are reported before any gauge comparison.
compute_result = RasCmdr.compute_plan(
event_plan, ras_object=ras, force_rerun=True, force_geompre=True,
verify=True, use_optimal_hdf_settings=True,
hdf_output_variables=[
"Cell Hydraulic Depth", "Water Surface", "Cell Precipitation Rate",
"Cell Cumulative Precipitation Depth",
],
)
if not bool(compute_result):
raise RuntimeError("Historical AORC event compute failed")
plan_hdf = ras.project_folder / f"{ras.project_name}.p{event_plan}.hdf"
messages = HdfResultsPlan.get_compute_messages_hdf_only(plan_hdf)
assert "complete process" in messages.lower()
assert not ("out-of-bounds" in messages.lower() and "2d cells" in messages.lower())
bco_path = ras.project_folder / f"{ras.project_name}.bco{event_plan}"
assert bco_path.exists()
bco_text = bco_path.read_text(encoding="utf-8", errors="replace")
diagnostic_pattern = re.compile(
r"\b(?:warning|fatal|failed|missing)\b|"
r"\berror(?::|\s+(?:reading|opening|processing|computing|occurred|encountered))",
flags=re.IGNORECASE,
)
bco_problem_lines = [line.strip() for line in bco_text.splitlines() if diagnostic_pattern.search(line)]
assert not bco_problem_lines, bco_problem_lines
cumulative = HdfResultsMesh.get_mesh_timeseries(
plan_hdf, MESH_NAME, "Cell Cumulative Precipitation Depth", truncate=False
)
depth = HdfResultsMesh.get_mesh_timeseries(
plan_hdf, MESH_NAME, "Cell Hydraulic Depth", truncate=False
)
final_cumulative = np.asarray(cumulative.values[-1], dtype=float)
active_mask = final_cumulative > 1e-6
assert int(np.count_nonzero(active_mask)) == mesh_cell_count
mesh_shg = mesh_points.to_crs("EPSG:5070")
expected_cell_in = source_total_mm.interp(
x=xr.DataArray(mesh_shg.geometry.x.to_numpy(), dims="cell_id"),
y=xr.DataArray(mesh_shg.geometry.y.to_numpy(), dims="cell_id"),
method="linear",
).values / 25.4
comparison_mask = active_mask & np.isfinite(expected_cell_in) & np.isfinite(final_cumulative)
comparison_error = final_cumulative[comparison_mask] - expected_cell_in[comparison_mask]
assert int(comparison_mask.sum()) >= int(0.85 * mesh_cell_count)
assert float(np.nanmax(np.abs(comparison_error))) <= 1e-5
depth_values = np.asarray(depth.values, dtype=float)
depth_values[depth_values < 0] = np.nan
with warnings.catch_warnings():
warnings.filterwarnings("ignore", message="All-NaN slice encountered", category=RuntimeWarning)
maximum_depth = np.nanmax(depth_values, axis=0)
assert float(np.nanmax(maximum_depth)) > 0.0
ws_error = HdfResultsMesh.get_mesh_max_ws_err(plan_hdf)
error_column = "cell_maximum_water_surface_error"
volume = HdfResultsPlan.get_volume_accounting(plan_hdf)
runtime_audit = pd.DataFrame([{
"complete process": True,
"precipitation coverage warning": False,
"BCO diagnostic lines": len(bco_problem_lines),
"maximum cell WSEL error (ft)": float(ws_error[error_column].max()),
"cells WSEL error >0.1 ft": int(np.count_nonzero(ws_error[error_column] > 0.1)),
"volume error (%)": float(volume.iloc[0]["Error Percent"]),
}])
forcing_summary = pd.DataFrame([{
"source-sampled active cells": int(comparison_mask.sum()),
"active final-HDF cells": int(np.count_nonzero(active_mask)),
"maximum source-to-final error (in)": float(np.nanmax(np.abs(comparison_error))),
"final-HDF mean depth (in)": float(np.nanmean(final_cumulative[comparison_mask])),
"maximum hydraulic depth (ft)": float(np.nanmax(maximum_depth)),
}])
display(runtime_audit.round(6))
display(forcing_summary.round(7))
plot_points = mesh_points.loc[comparison_mask].copy()
plot_points["cumulative_in"] = final_cumulative[comparison_mask]
depth_map = mesh_points.copy()
depth_map["maximum_depth_ft"] = maximum_depth
fig, (ax_rain, ax_depth) = plt.subplots(1, 2, figsize=(15, 5.5), constrained_layout=True)
plot_points.plot(ax=ax_rain, column="cumulative_in", cmap="Blues", markersize=3,
legend=True, legend_kwds={"label": "Final cumulative depth (in)"})
mesh_areas.boundary.plot(ax=ax_rain, color="#263238", linewidth=0.8)
ax_rain.set(title="Solver-Applied Historical AORC", xlabel="Easting (ft)", ylabel="Northing (ft)")
depth_map.plot(ax=ax_depth, column="maximum_depth_ft", cmap="Blues", markersize=3,
legend=True, legend_kwds={"label": "Maximum hydraulic depth (ft)"})
mesh_areas.boundary.plot(ax=ax_depth, color="#263238", linewidth=0.8)
high_error = ws_error.loc[ws_error[error_column] > 0.1]
if not high_error.empty:
high_error.plot(ax=ax_depth, color="#ffcc00", edgecolor="black", markersize=40, label="WSEL error >0.1 ft")
ax_depth.legend(loc="best")
ax_depth.set(title="Historical-Event Hydraulic Result", xlabel="Easting (ft)", ylabel="Northing (ft)")
plt.show()
| complete process | precipitation coverage warning | BCO diagnostic lines | maximum cell WSEL error (ft) | cells WSEL error >0.1 ft | volume error (%) | |
|---|---|---|---|---|---|---|
| 0 | True | False | 0 | 0.009999 | 0 | 0.001523 |
| source-sampled active cells | active final-HDF cells | maximum source-to-final error (in) | final-HDF mean depth (in) | maximum hydraulic depth (ft) | |
|---|---|---|---|---|---|
| 0 | 18066 | 18066 | 0.000003 | 2.75149 | 58.836895 |

Diagnostic USGS stage comparison¶
Observed gage height is converted to water-surface elevation with the reported gage datum. USGS UTC timestamps are converted to local Eastern time before the series is interpolated to modeled timestamps. The model series comes only from the newly computed historical-event HDF at the nearest result-center slot. The metrics describe this uncalibrated setup; they are not acceptance criteria.
observed_stage = retrieve_stage_data(
site_id=VALIDATION_GAUGE,
start_datetime=SIM_START.strftime("%Y-%m-%d"),
end_datetime=SIM_END.strftime("%Y-%m-%d"),
data_type="iv",
)
observed_stage = observed_stage[["datetime", "value"]].copy()
observed_stage["datetime"] = (
pd.to_datetime(observed_stage["datetime"], utc=True)
.dt.tz_convert("America/New_York")
.dt.tz_localize(None)
)
observed_stage["value"] = pd.to_numeric(observed_stage["value"], errors="coerce") + float(gauge_meta["gage_datum_ft"])
observed_stage = observed_stage.dropna().sort_values("datetime")
assert not observed_stage.empty
mesh_geometry = mesh_points.geometry
gauge_point = gauge_model.geometry.iloc[0]
distances = mesh_geometry.distance(gauge_point)
nearest_row = int(distances.idxmin())
nearest_cell_id = int(mesh_points.loc[nearest_row, "cell_id"])
nearest_distance_ft = float(distances.loc[nearest_row])
water_surface = HdfResultsMesh.get_mesh_timeseries(
plan_hdf, MESH_NAME, "Water Surface", truncate=False
)
model_times = pd.DatetimeIndex(pd.to_datetime(water_surface.coords["time"].values))
model_wse = np.asarray(water_surface.values[:, nearest_row], dtype=float)
model_wse[model_wse < -1.0e20] = np.nan
model_frame = pd.DataFrame({"datetime": model_times, "modeled": model_wse}).dropna()
overlap_start = max(model_frame["datetime"].min(), observed_stage["datetime"].min())
overlap_end = min(model_frame["datetime"].max(), observed_stage["datetime"].max())
assert overlap_start < overlap_end
aligned = model_frame.loc[
(model_frame["datetime"] >= overlap_start) & (model_frame["datetime"] <= overlap_end)
].copy()
obs_overlap = observed_stage.loc[
(observed_stage["datetime"] >= overlap_start) & (observed_stage["datetime"] <= overlap_end)
]
model_epoch_seconds = np.asarray(aligned["datetime"], dtype="datetime64[ns]").astype("int64") / 1e9
observed_epoch_seconds = np.asarray(obs_overlap["datetime"], dtype="datetime64[ns]").astype("int64") / 1e9
aligned["observed"] = np.interp(
model_epoch_seconds,
observed_epoch_seconds,
obs_overlap["value"].to_numpy(dtype=float),
)
aligned["residual"] = aligned["modeled"] - aligned["observed"]
assert np.isfinite(aligned[["modeled", "observed", "residual"]].to_numpy()).all()
stage_metrics = pd.DataFrame([{
"nearest result-center cell": nearest_cell_id,
"gauge-to-cell distance (ft)": nearest_distance_ft,
"comparison timesteps": len(aligned),
"bias (ft)": float(aligned["residual"].mean()),
"MAE (ft)": float(aligned["residual"].abs().mean()),
"RMSE (ft)": float(np.sqrt(np.mean(aligned["residual"] ** 2))),
"observed peak WSE (ft)": float(aligned["observed"].max()),
"modeled peak WSE (ft)": float(aligned["modeled"].max()),
}])
display(stage_metrics.round(3))
fig, (ax_series, ax_scatter) = plt.subplots(1, 2, figsize=(15, 5.2), constrained_layout=True)
ax_series.plot(aligned["datetime"], aligned["observed"], color="#2b6f9f", label="Observed USGS WSE")
ax_series.plot(aligned["datetime"], aligned["modeled"], color="#b5453c", linestyle="--", label="Modeled nearest-cell WSE")
ax_series.set(title="Diagnostic Stage/WSE Comparison", xlabel="Time", ylabel="Water-surface elevation (ft)")
ax_series.tick_params(axis="x", rotation=30)
ax_series.grid(alpha=0.25)
ax_series.legend()
ax_scatter.scatter(aligned["observed"], aligned["modeled"], s=12, alpha=0.55)
minimum = float(min(aligned["observed"].min(), aligned["modeled"].min()))
maximum = float(max(aligned["observed"].max(), aligned["modeled"].max()))
ax_scatter.plot([minimum, maximum], [minimum, maximum], color="black", linestyle="--", label="1:1")
ax_scatter.set(title="Observed vs Modeled WSE", xlabel="Observed WSE (ft)", ylabel="Modeled WSE (ft)")
ax_scatter.grid(alpha=0.25)
ax_scatter.legend()
plt.show()
print("Interpretation: diagnostic only; historical boundary hydrographs and gate operations were not supplied.")
| nearest result-center cell | gauge-to-cell distance (ft) | comparison timesteps | bias (ft) | MAE (ft) | RMSE (ft) | observed peak WSE (ft) | modeled peak WSE (ft) | |
|---|---|---|---|---|---|---|---|---|
| 0 | 10562 | 97.159 | 289 | -2.075 | 2.075 | 2.417 | 571.03 | 568.378 |

Interpretation: diagnostic only; historical boundary hydrographs and gate operations were not supplied.
Completion record¶
The checks below qualify the forcing and compute path and confirm that the USGS comparison uses the newly created event HDF. They deliberately do not impose a model-skill threshold on an uncalibrated fixture.
completion_checks = pd.Series({
"archived AORC source has exact 48-hour timing": len(forcing_times) == EXPECTED_FRAMES and forcing_times[0] == FIRST_VALID_TIME and forcing_times[-1] == SIM_END,
"durable native-HDF precipitation authored": imported_cumulative.shape[0] == EXPECTED_FRAMES + 1 and np.allclose(imported_cumulative[0], 0.0),
"temporary HDF exactly reproduces source": float(np.nanmax(np.abs(precompute_error))) <= 5e-6,
"HEC-RAS compute/runtime/BCO gates pass": bool(compute_result) and "complete process" in messages.lower() and not bco_problem_lines,
"final HDF exactly reproduces active-cell source": float(np.nanmax(np.abs(comparison_error))) <= 1e-5,
"hydraulic output is finite and positive": float(np.nanmax(maximum_depth)) > 0.0,
"USGS comparison uses event HDF and reported datum": len(aligned) > 0 and float(gauge_meta["gage_datum_ft"]) > 0.0,
"USGS result is labeled diagnostic rather than calibrated": True,
}, name="passed").to_frame()
display(completion_checks)
assert completion_checks["passed"].all()
print("Historical AORC event forcing and diagnostic comparison complete.")
print(f"HEC-RAS {RAS_VERSION}; p{event_plan}; AORC {SIM_START} to {SIM_END}; USGS {VALIDATION_GAUGE}.")
print("The USGS comparison is not a calibration validation because historical boundaries and operations were not supplied.")
print("Review all HEC-RAS runtime and BCO messages, precipitation maps, timing, units, terrain coverage, mass balance, convergence, hydraulic plausibility, gauge datum/location, and historical inputs manually.")
| passed | |
|---|---|
| archived AORC source has exact 48-hour timing | True |
| durable native-HDF precipitation authored | True |
| temporary HDF exactly reproduces source | True |
| HEC-RAS compute/runtime/BCO gates pass | True |
| final HDF exactly reproduces active-cell source | True |
| hydraulic output is finite and positive | True |
| USGS comparison uses event HDF and reported datum | True |
| USGS result is labeled diagnostic rather than calibrated | True |
Historical AORC event forcing and diagnostic comparison complete.
HEC-RAS 7.0; p07; AORC 2020-12-24 00:00:00 to 2020-12-26 00:00:00; USGS 01548005.
The USGS comparison is not a calibration validation because historical boundaries and operations were not supplied.
Review all HEC-RAS runtime and BCO messages, precipitation maps, timing, units, terrain coverage, mass balance, convergence, hydraulic plausibility, gauge datum/location, and historical inputs manually.