Data Reference

Column schemas for every layer exported by hms2cng. All values below are from real HMS example projects.

---

Geometry Layers

Exported by hms2cng geometry or get_basin_layer_gdf(). Source is the .basin file (canvas coordinates). CRS is auto-detected from the HMS project; if not detected, coordinates remain in the project's native unit (e.g. US Survey Feet or metres).

subbasins

Geometry: Point (subbasin centroid from HMS canvas coordinates) Source: .basin file

Column	Type	Example
name	str	'74006'
area	float64	19.27 (project area units, typically sq mi)
downstream	str	'Station I'
loss_method	str	'Soil Moisture Account'
transform_method	str	'Clark'
baseflow_method	str	'Linear Reservoir'
percent_impervious	float64	0.0
canvas_x	float64	241449.68 (project CRS units)
canvas_y	float64	3512247.90 (project CRS units)
geometry	Point	POINT (241449.68 3512247.90)

junctions

Geometry: Point Source: .basin file

Column	Type	Example
name	str	'Station I'
downstream	str \| None	None (outlet has no downstream)
canvas_x	float64	245683.85
canvas_y	float64	3506828.36
geometry	Point	POINT (245683.85 3506828.36)

reaches

Geometry: LineString (from-node → to-node) Source: .basin file

Column	Type	Example
name	str	'Local Route'
downstream	str	'Detention Basin'
route_method	str	'Muskingum'
canvas_x	float64	772762.98 (to-node X)
canvas_y	float64	3957375.07 (to-node Y)
from_canvas_x	float64	773135.27 (from-node X)
from_canvas_y	float64	3957609.69 (from-node Y)
geometry	LineString	LINESTRING (773135.27 3957609.69, 772762.98 3957375.07)

watershed

Geometry: Polygon (outer boundary of the modeled watershed) Source: .map file (requires HMS terrain preprocessing)

Column	Type	Example
geometry	Polygon	POLYGON ((...))

Note

The watershed layer has no attribute columns — it is the boundary polygon only. Requires a .map file alongside the .basin file.

diversions, reservoirs, sources, sinks

Same schema as junctions (Point geometry with name, downstream, canvas_x, canvas_y). Present only if those element types exist in the .basin file.

---

SQLite Layers

Exported from the .sqlite database generated by HMS terrain preprocessing (GeoHMS / RAS Mapper). Only available for projects that have run terrain analysis.

subbasin_polygons

Geometry: Polygon (delineated subbasin boundaries from terrain analysis) Source: .sqlite file

Column	Type	Example
name	str	'S_ClemarCrT1_01'
centroid_x	float64	0.0 (may be unpopulated)
centroid_y	float64	0.0
area_sqkm	float64	2.14
latitude	float64	31.95
longitude	float64	-93.86
basinid	int32	42
geometry	Polygon	POLYGON ((-93.856 31.951, ...))

longest_flowpaths / centroidal_flowpaths / teneightyfive_flowpaths

Geometry: LineString (flow path lines from terrain analysis) Source: .sqlite file

Columns vary by project. Typically include name, length, and geometry.

subbasin_statistics

Geometry: Point (subbasin centroid from .basin canvas coordinates, joined with sqlite stats) Source: .sqlite + .basin files

Columns vary by project. Typically include name, area, slope, longest_flowpath_length, and geometry.

---

Results Layer

Exported by hms2cng results or export_hms_results(). Parses RUN_*.results XML files (summary statistics only — not DSS time series). The result is the geometry layer spatially joined with statistics.

Subbasin outflow (element_type="subbasin", variable="Outflow")

Geometry: Point (subbasin centroid, same as the subbasins geometry layer)

Column	Type	Example	Notes
name	str	'Upper'	Join key with geometry
area	float64	7.5	From basin file
downstream	str	'J1'	From basin file
loss_method	str	'Deficit Constant'	From basin file
transform_method	str	'SCS'	From basin file
baseflow_method	str	'None'	From basin file
percent_impervious	float64	15.0	From basin file
canvas_x	float64	773463.23	From basin file
canvas_y	float64	3957698.22	From basin file
geometry	Point	POINT (-83.977 35.725)	Reprojected to EPSG:4326
element_type	str	'subbasin'	HMS element class
run_name	str	'Minimum Facility + Pump'	From <RunName> in XML
variable_prefix	str	'Outflow'	The variable exported
max_value	float64	1185.18	Peak value
time_of_max	datetime64[us]	1951-09-21 22:00:00	Timestamp of peak
min_value	float64	0.0	Minimum value
time_of_min	datetime64[us]	1951-01-01 01:00:00	Timestamp of minimum
mean_value	float64	17.88	Time-averaged mean
volume	float64	12946.4	Total volume
depth	float64	32.37	Depth equivalent
units	str	'CFS'	Flow units

Tip

The results layer is a spatial join of geometry + statistics. Subbasins without results entries (e.g. no simulation run) are dropped. Use element_type="all" to include junctions, reaches, and other element types in one output.

---

Consolidated Project Archive

Written by hms2cng project or export_full_project(). Produces a single GeoParquet with a layer discriminator column:

output_dir/
├── {project_slug}.parquet    # ALL geometry + results
└── manifest.json             # JSON catalog (schema v2.0)

Query specific layers:

SELECT * FROM 'project.parquet' WHERE layer = 'subbasins'
SELECT * FROM 'project.parquet' WHERE layer = 'outflow' AND run_name = 'Run 1'
SELECT layer, COUNT(*) FROM 'project.parquet' GROUP BY layer

The layer column contains geometry layer names (subbasins, reaches, junctions, watershed, ...) and result variable names (outflow, stage, inflow, depth).

---

Project Registry Parquets

Written by hms2cng manifest -o OUTPUT_DIR or export_project_manifest(). These three files form a queryable index for cross-project analytics.

manifest.parquet

One row per project. Project-level summary.

Column	Type	Example
project_name	str	'river_bend'
project_file	str	'C:/HMS/river_bend/river_bend.hms'
hms_version	str	'4.11'
crs_epsg	str	'EPSG:26914'
is_gridded	bool	False
num_basin_models	int	3
num_met_models	int	2
num_control_specs	int	2
num_runs	int	3
basin_models	str	'["Basin 1", "Basin 2", "Basin 3"]' (JSON)
met_models	str	'["PMF", "100yr"]' (JSON)
run_names	str	'["PMF Run", "100yr Run"]' (JSON)
export_timestamp	str	'2025-06-01T12:00:00+00:00'

run_registry.parquet

One row per simulation run. Links each run to its basin model, met model, control spec, and results file.

Column	Type	Example
project_name	str	'river_bend'
run_name	str	'PMF Run'
run_slug	str	'pmf_run'
basin_model	str	'Basin 1'
met_model	str	'PMF'
control_spec	str	'Control 1'
start_date	datetime64	1979-10-23 00:00:00
end_date	datetime64	1979-10-27 00:00:00
time_interval_minutes	float64	60.0
duration_hours	float64	96.0
last_execution_date	str	'23 May 2025'
last_execution_time	str	'14:32:11'
results_file	str	'C:/HMS/river_bend/results/RUN_PMF Run.results'
has_results	bool	True

basin_inventory.parquet

One row per basin model. Element counts and methods for each basin file.

Column	Type	Example
project_name	str	'river_bend'
basin_model	str	'Basin 1'
basin_slug	str	'basin_1'
basin_file	str	'C:/HMS/river_bend/Basin 1.basin'
description	str	'Calibration basin'
num_subbasins	int32	5
num_reaches	int32	3
num_junctions	int32	4
num_reservoirs	int32	0
total_area	float64	42.7
loss_methods	str	'["SCS Curve Number"]' (JSON)
transform_methods	str	'["SCS Unit Hydrograph"]' (JSON)
routing_methods	str	'["Muskingum"]' (JSON)

Tip

Use the run_registry to build cross-project DuckDB catalogs:

SELECT project_name, run_name, basin_model, met_model
FROM read_parquet('archives/*/run_registry.parquet', union_by_name=true)
WHERE has_results = true
ORDER BY project_name, run_name

---

CRS Handling

All layers are exported to EPSG:4326 (WGS84) by default when the project CRS is successfully auto-detected. The canvas_x / canvas_y columns always retain the original project coordinates (e.g. US Survey Feet) for reference.

from hms2cng.geometry import get_basin_layer_gdf

gdf = get_basin_layer_gdf("project.basin", layer="subbasins")
print(gdf.crs)        # EPSG:4326 (if CRS detected), else None
print(gdf.canvas_x)   # original project units always preserved

Override CRS with:

hms2cng geometry project.basin out.parquet --crs EPSG:2278 --out-crs EPSG:4326

---

Full Extraction Example

from pathlib import Path
from hms_commander import HmsExamples
from hms2cng.geometry import export_basin_geometry
from hms2cng.results import export_hms_results
import geopandas as gpd

# Auto-extract example project
project = HmsExamples.extract_project("tifton")
basin   = next(project.glob("*.basin"))
results = project / "results"

out = Path("out")
out.mkdir(exist_ok=True)

# --- Geometry layers ---
LAYERS = ["subbasins", "junctions", "reaches", "watershed",
          "subbasin_polygons", "longest_flowpaths"]

for layer in LAYERS:
    try:
        export_basin_geometry(basin, out / f"{layer}.parquet", layer=layer)
        gdf = gpd.read_parquet(out / f"{layer}.parquet")
        print(f"{layer:25s}  {len(gdf):4d} rows  {gdf.geometry.iloc[0].geom_type}")
    except (ValueError, FileNotFoundError) as e:
        print(f"{layer:25s}  skipped — {e}")

# --- Results ---
export_hms_results(results, out / "subbasin_outflow.parquet",
                   element_type="subbasin", variable="Outflow")
gdf_results = gpd.read_parquet(out / "subbasin_outflow.parquet")
print(f"\nResults columns: {list(gdf_results.columns)}")
print(gdf_results[["name", "max_value", "time_of_max", "units"]].head())

Typical console output:

subbasins                    131 rows  Point
junctions                     42 rows  Point
reaches                       38 rows  LineString
watershed                      1 rows  Polygon
subbasin_polygons            131 rows  Polygon
longest_flowpaths            131 rows  LineString

Results columns: ['name', 'area', 'downstream', 'loss_method', 'transform_method',
                  'baseflow_method', 'percent_impervious', 'canvas_x', 'canvas_y',
                  'geometry', 'element_type', 'run_name', 'variable_prefix',
                  'max_value', 'time_of_max', 'min_value', 'time_of_min',
                  'mean_value', 'volume', 'depth', 'units']

         name  max_value         time_of_max units
0       Upper    1185.18 1951-09-21 22:00:00   CFS
1       Lower     892.44 1951-09-21 23:00:00   CFS