Profile Line Flow Extraction¶
Extract a hydrograph and peak flow for one named line from completed 2D results. This is a flow-versus-time example, not a velocity/depth-versus-station plot. Use 416 for station profiles and 314 for reference features authored before computation and plotted in batches.
| Required input | Returned output |
|---|---|
| Completed plan HDF, exact line/mesh names, and (for an ad-hoc line) its Mapper feature source | Time-series DataFrame with time, flow, selection source, face count, and direction metadata |
| Same inputs for the peak helper | Peak time and flow with the same selection provenance |
The current canonical methods use pythonnet and HEC-RAS RasMapperLib.
They first try a precomputed hydrograph that RasMapperLib associates with the
reference line (try_read_ref_line_flow); its provenance has not been independently
qualified as solver-recorded rather than observed/event-associated data. Otherwise
they read selected face flows, using native Mapper perimeter-face selection for
an ad-hoc line. Use HdfResultsXsec.get_ref_lines_timeseries() to read the
solver-recorded HDF reference-line result group explicitly. The explicitly named _legacy method is the separate offline
reconstruction path. See 2D profile and reference workflows and native profile API reference for the contracts.
Saved-run scope: the retained Chippewa tables report
selection_source="profile_lines_geometry" with six faces. They document the
historical reconstruction run, not a fresh test of the current canonical native
path. Code and outputs are unchanged in this editorial update. A current native
rerun is required before treating these outputs as native-runtime qualification.
The committed native regression fixture for the same Chippewa plan/line/mesh
records seven faces (rasmapper_perimeter_faces), a first absolute flow of
18,093.43 cfs, first signed flow of -18,093.43 cfs, and peak absolute flow
of 38,000.63 cfs. The historical outputs below show six faces, 1,948.33 cfs
absolute and +494.81 cfs signed at the first time, and 2,316.14 cfs peak.
Rerunning the unchanged code against that fixture is therefore expected to
change the face set and the numerical results substantially. These are different
extraction paths, not interchangeable validation targets; this comparison does
not establish which flow should be accepted for engineering use.
See the native regression tests
and retained native CSV.
from pathlib import Path
import os
import matplotlib.pyplot as plt
import pandas as pd
from ras_commander import HdfResultsMesh
Development mode: run this notebook with PYTHONPATH pointed at the repository root when testing local source changes. The committed import cell above intentionally uses the installed/importable package form.
Inputs, Direction, And Comparison Scope¶
The input folder is an external completed Chippewa validation fixture, not a
bundled dataset. Set CLB214_PROFILE_LINE_VALIDATION or supply your own completed
plan and line source. The selected-face path requires saved Face Flow output;
a map image alone is insufficient.
Inspect selection_source before interpreting the result:
- With
selection_source="try_read_ref_line_flow", the native-associated precomputed hydrograph is used as returned;direction="absolute"takes its magnitude. Its solver-versus-observed provenance remains unqualified. Do not treat the native call alone as proof that these are computed model results. - A selected-face result with
direction="absolute"sums individual face-flow magnitudes. Withdirection="signed", it sums their native signs. Those signs belong to mesh face orientation, not a common transect-normal convention. Neither operation automatically establishes net downstream discharge.
The signed/absolute comparison exposes cancellation and selection behavior. Agreement with the optional manual face-sum CSV checks that calculation, not agreement with a flow-weighted Mapper statistic, recorded line hydrograph, or measured discharge. Review selected faces, wet/dry conditions, structures, line orientation, and possible recirculation before using a peak for design.
The retained plot labels flow in cfs for this project. For another model, read returned units metadata and confirm units before setting labels. The peak is selected from saved result times, not necessarily the computational-timestep peak. For many lines, repeat with explicit line/mesh names and retain provenance with each exported plot.
validation_root = Path(
os.environ.get(
"CLB214_PROFILE_LINE_VALIDATION",
r"H:/Symphony/ras-commander/CLB-214/profile_line_flow_validation",
)
)
project_dir = validation_root / "project" / "Chippewa_2D_profile_line_flow"
plan_hdf = project_dir / "Chippewa_2D.p02.hdf"
profile_lines_path = validation_root / "profile_line_input"
line_name = "Upstream"
mesh_name = "Perimeter 1"
if not plan_hdf.exists():
raise FileNotFoundError(
f"Completed plan HDF not found: {plan_hdf}. "
"Set CLB214_PROFILE_LINE_VALIDATION or replace plan_hdf/profile_lines_path "
"with a completed project that outputs Face Flow."
)
print(f"Plan HDF: {plan_hdf}")
print(f"Profile line source: {profile_lines_path}")
Plan HDF: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
Profile line source: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\profile_line_input
flow_ts = HdfResultsMesh.get_profile_line_flow_timeseries(
plan_hdf,
line_name,
mesh_name=mesh_name,
profile_lines_path=profile_lines_path,
direction="absolute",
)
peak_q = HdfResultsMesh.get_profile_line_peak_flow(
plan_hdf,
line_name,
mesh_name=mesh_name,
profile_lines_path=profile_lines_path,
)
display(flow_ts.head())
display(peak_q)
2026-05-01 12:58:20 - ras_commander.hdf.HdfResultsMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:20 - ras_commander.hdf.HdfResultsMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:20 - ras_commander.hdf.HdfMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.g01.hdf
2026-05-01 12:58:20 - ras_commander.hdf.HdfMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.g01.hdf
2026-05-01 12:58:20 - ras_commander.hdf.HdfMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:20 - ras_commander.hdf.HdfMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:20 - ras_commander.hdf.HdfMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:20 - ras_commander.hdf.HdfMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:20 - ras_commander.hdf.HdfBase - INFO - Using HDF file from h5py.File object: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:20 - ras_commander.hdf.HdfBase - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:20 - ras_commander.hdf.HdfBase - CRITICAL - No valid projection found. Checked:
1. HDF file projection attribute: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2. RASMapper projection file H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\.Winona_Upload\LifeSim model\Winona Levee SQRA 2019\RAS\AW\MMC_Projection.prj found in RASMapper file, but was invalid
To fix this:
1. Open RASMapper
2. Click Map > Set Projection
3. Select an appropriate projection file or coordinate system
4. Save the RASMapper project
2026-05-01 12:58:20 - ras_commander.hdf.HdfMesh - INFO - Found 6 faces along profile line
2026-05-01 12:58:20 - ras_commander.hdf.HdfResultsMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:20 - ras_commander.hdf.HdfResultsMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:20 - ras_commander.hdf.HdfResultsMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:20 - ras_commander.hdf.HdfResultsMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:21 - ras_commander.hdf.HdfResultsMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:21 - ras_commander.hdf.HdfResultsMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.g01.hdf
2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.g01.hdf
2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:21 - ras_commander.hdf.HdfBase - INFO - Using HDF file from h5py.File object: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:21 - ras_commander.hdf.HdfBase - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:21 - ras_commander.hdf.HdfBase - CRITICAL - No valid projection found. Checked:
1. HDF file projection attribute: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2. RASMapper projection file H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\.Winona_Upload\LifeSim model\Winona Levee SQRA 2019\RAS\AW\MMC_Projection.prj found in RASMapper file, but was invalid
To fix this:
1. Open RASMapper
2. Click Map > Set Projection
3. Select an appropriate projection file or coordinate system
4. Save the RASMapper project
2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Found 6 faces along profile line
2026-05-01 12:58:21 - ras_commander.hdf.HdfResultsMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:21 - ras_commander.hdf.HdfResultsMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
| time | flow | line_name | mesh_name | direction | face_count | selection_source | |
|---|---|---|---|---|---|---|---|
| 0 | 2019-04-02 00:00:00 | 1948.334485 | Upstream | Perimeter 1 | absolute | 6 | profile_lines_geometry |
| 1 | 2019-04-02 00:30:00 | 1945.119192 | Upstream | Perimeter 1 | absolute | 6 | profile_lines_geometry |
| 2 | 2019-04-02 01:00:00 | 1919.116215 | Upstream | Perimeter 1 | absolute | 6 | profile_lines_geometry |
| 3 | 2019-04-02 01:30:00 | 1881.967214 | Upstream | Perimeter 1 | absolute | 6 | profile_lines_geometry |
| 4 | 2019-04-02 02:00:00 | 1849.279263 | Upstream | Perimeter 1 | absolute | 6 | profile_lines_geometry |
| line_name | mesh_name | peak_time | peak_flow | direction | face_count | selection_source | |
|---|---|---|---|---|---|---|---|
| 0 | Upstream | Perimeter 1 | 2019-04-21 01:00:00 | 2316.140572 | absolute | 6 | profile_lines_geometry |
signed_flow_ts = HdfResultsMesh.get_profile_line_flow_timeseries(
plan_hdf,
line_name,
mesh_name=mesh_name,
profile_lines_path=profile_lines_path,
direction="signed",
)
comparison = flow_ts[["time", "flow"]].rename(columns={"flow": "absolute_flow"}).merge(
signed_flow_ts[["time", "flow"]].rename(columns={"flow": "signed_flow"}),
on="time",
)
display(comparison.head())
2026-05-01 12:58:21 - ras_commander.hdf.HdfResultsMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:21 - ras_commander.hdf.HdfResultsMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.g01.hdf
2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.g01.hdf
2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:21 - ras_commander.hdf.HdfMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:21 - ras_commander.hdf.HdfBase - INFO - Using HDF file from h5py.File object: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:21 - ras_commander.hdf.HdfBase - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:21 - ras_commander.hdf.HdfBase - CRITICAL - No valid projection found. Checked:
1. HDF file projection attribute: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2. RASMapper projection file H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\.Winona_Upload\LifeSim model\Winona Levee SQRA 2019\RAS\AW\MMC_Projection.prj found in RASMapper file, but was invalid
To fix this:
1. Open RASMapper
2. Click Map > Set Projection
3. Select an appropriate projection file or coordinate system
4. Save the RASMapper project
2026-05-01 12:58:22 - ras_commander.hdf.HdfMesh - INFO - Found 6 faces along profile line
2026-05-01 12:58:22 - ras_commander.hdf.HdfResultsMesh - INFO - Using existing Path object HDF file: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
2026-05-01 12:58:22 - ras_commander.hdf.HdfResultsMesh - INFO - Final validated file path: H:\Symphony\ras-commander\CLB-214\profile_line_flow_validation\project\Chippewa_2D_profile_line_flow\Chippewa_2D.p02.hdf
| time | absolute_flow | signed_flow | |
|---|---|---|---|
| 0 | 2019-04-02 00:00:00 | 1948.334485 | 494.805432 |
| 1 | 2019-04-02 00:30:00 | 1945.119192 | 490.561087 |
| 2 | 2019-04-02 01:00:00 | 1919.116215 | 466.979741 |
| 3 | 2019-04-02 01:30:00 | 1881.967214 | 432.740896 |
| 4 | 2019-04-02 02:00:00 | 1849.279263 | 406.301601 |
manual_validation_csv = validation_root / "manual_face_flow_validation.csv"
if manual_validation_csv.exists():
manual = pd.read_csv(manual_validation_csv, parse_dates=["time"])
validation = comparison.merge(manual, on="time")
print(
"Max absolute-flow difference:",
validation["absolute_difference"].abs().max(),
)
print(
"Max signed-flow difference:",
validation["signed_difference"].abs().max(),
)
Max absolute-flow difference: 0.0
Max signed-flow difference: 0.0
fig, ax = plt.subplots(figsize=(10, 4))
ax.plot(flow_ts["time"], flow_ts["flow"], label="Absolute flow")
ax.plot(signed_flow_ts["time"], signed_flow_ts["flow"], label="Signed flow")
ax.set_ylabel("Flow (cfs)")
ax.set_title(f"{line_name} profile-line flow")
ax.legend()
ax.grid(True, alpha=0.3)
fig.autofmt_xdate()
plt.show()
