# install.packages("devtools") # You only need this if this is your very first time opening RStudio
# install.packages("BiocManager") # You only need this if this is your very first time opening RStudio
# BiocManager::install("rhdf5") # You only need this if this is your very first time opening RStudio
# utils::remove.packages("RRASSLER") # You only need to run this if you have a previous install and need to wipe it
remotes::install_github("NOAA-OWP/RRASSLER") # If it asks for package updates: press 1
library(data.table)
RRASSLER::marco() # A "hello world" testRRASSLER
Executive Summary
The HEC-RAS model format, both as stand alone models or in archive databases, are incompatible for end users whose use case includes widespread accounting and deployment of that data as inputs into other workflows. This tool should be deployed to ingest HEC-RAS models into a “HECRAS_model_catalog”, a normalized and spatialized representation of those models with the requisite metadata and formatted structure needed to mesh more seamlessly with national scale hydrofabric efforts and data models, and applications such as T-Route and RAS2FIM. See the package documentation, and the repo itself, for more details.
Publicly facing “HECRAS_model_catalog”
See the sample RRASSLER catalog here; and a STAC’d version of a generated catalog from publicly available RAS models (primarily sourced from FEMA Region 6) here. Although not at all related to this effort, you can find Dewberries interpretation of a HEC-RAS catalog based on efforts expounded on in (Lawler et al. 2025) here.
Installation
As the badges above indicate, this package is Active and Stable. Install RRASSLER from GitHub with:
Note: RRASSLER generates data as part of it’s processing. Although every effort has been made to ensure that the form of that data is not so inflexible that future bug-fixes and enhancements break the resulting structure, we can make no guarantee that changes made, particularly to parsing process and accuracy, edge case handling, and ultimately accounting; would not require “reprocessing” records, something that is best accomplished using the original data. As noted above, this package and several of it’s cohort are still actively being developed. Although the core logic of record creation has been stabilized for the time being, the “final” form of these tables is still in flux.
Note: On a GFE and this didn’t work? Try tips I outline here.
Tutorials
There are several tutorials available at the Article index including:
- Data Model: The data standard we are building to.
- Ingest steps: What RRASSLER is doing to data?
- Deploying RRASSLER: How to make your own “HEC-RAS model catalog”.
- Mapping RRASSLER: Adding (geographic) context to our data.
See the package documentation for function references and additional information.
Relevant and Related References
- There are several formal publications associated with this effort including…
- A poster presentation from AGU 2023
- A paper in prep.
- Model debug: code snippets useful in learning how to interact with RAS data and RRASSLER outputs, used in package development, and model debugging.
- FEMA_BLE by Ali Forghani: a pythonic implementation of a HEC-RAS model reader.
- USACE/mcat-ras: A set of tools which enable cloud based model access, based in GO.
- fema/rashdf: A set of python tools which read .HDF files into a geodataframe.
- fema-ffrd/ras-stac: A set of tools which enable cloud based model access, based in Python.
- psu-efd/pyHMT2D: Includes tools which provide RAS model I/O, among other utilities, based in Python.
- A suite of FEMA related tools including validation and checking of models and some that convert older models into HEC-RAS models.
- A utility to help write HEC formatted timeseries (.DSS files).
- a (slightly older) RAS enabled docker file.
- (Goodell, n.d.): An invaluable resource in decrypting the RAS model format.
Timing
The following timings were tested only once and are provided to help gage how much investment needs to go into processing. These results of course are a function of the mode RRASSLIER is run in, hardware, and particular set of models you are ingesting and is by no means an exhaustive or comprehensive set of tables. Run as you would find demonstrated in Deploying RRASSLER
Ingest timing
Show an example of how this was run
ingest_into_database(path_to_ras_dbase = ras_dbase,
top_of_dir_to_scrape = "./inst/extdata/sample_ras/timing_samples/5_models",
code_to_place_in_source = "test: FEMA6",
proj_override = "EPSG:2277",
apply_vdat_trans = FALSE,is_quiet = FALSE,is_verbose = TRUE,overwrite = FALSE,parallel_proc = FALSE)| PC hardware | Number of models | Runtime (hours) |
|---|---|---|
| 1 | 5 | 0.010 |
| 1 | 50 | 0.087 |
| 1 | 500 | 2.494 |
| 1 | 12491 | 82.431 |
| 2 | 12096 | 546.200 |
Footprint timing
| PC hardware | Number of models | Runtime (hours) |
|---|---|---|
| 1 | 5 | 0.0001 |
| 1 | 50 | 0.0010 |
| 1 | 500 | 2.4940 |
| 1 | 12491 | 2.9500 |
| 1 | 13700 | 3.6370 |
| 2 | 24587 | 32.4280 |
Notes: PC ID 1 was RRASSLER, run on a docker’d image on a Intel Core i5-9600K CPU @ 3.7 GHz with 32 gigs of RAM available and moderate background use. PC 2 is a GFE, running RRASSLER on RStudio on a 13th Gen Intel Core i7-1355U CPU @ 1.7 GHz with 32 gigs of RAM available and light background use.
Explanations
Statement of need
There are few hydraulic models as prolific as HEC-RAS, and since it’s first named release in 1995 users have created these models using public and private data and countless hours of engineering scrutinization in order to generate the best possible purpose-built representation of the world. Like any model, some level of input massaging is necessary in order to get the data into the specified mathematical format a model requires. Like most domain specific software solutions, that massaging was rather, forceful, to the point of permanently altering the shape of those inputs into something that most geospatial data readers are unable to handle. This creates a great deal of friction both in terms of model accountability and interoperability, particularly when you take the standpoint as a model consumer. The R based HEC-RAS Wrestler (RRASSLER) is here to mediate that. By internally versioning and aligning data and pointers, the resulting structure provides a bottoms up approach amenable to walking continental scale applications back to the specific point, cross section, and HEC-RAS model they were sourced from. See this in visual form here.
Why not just upload model to git?
Aside from the poor use of the tool, there are a few reasons not to do this. First, without a flatter structure you are still left to guess at where in the stack of folders your relevant model is. Naming collision will be more frequent since the models space is not forced into the schema, and although version controlling the data would be more robust (one of the principle features of GIT), none of the added benefits of the F.A.I.R.-ification that RRASSLER accomplishes are realized.
Is this just a HEC-RAS data reader?
Although this utility does implement a reader, it accomplishes far more than simply reading in data. While implementing the HEC-RAS format as a driver for inclusion in the most common reader (gdal) could in theory be possible, that solves only a few of the limitations encountered in using these models and does not fully address many of the concerns that we need to overcome. This is also a slightly more flexible reader in that larger context of related tools. Many parse only .HDF files, whereas RRASSLER parses and uses both in the spatialization of the model.
The HEC-RAS Model Format
See my HEC-RAS data page for a deeper dive into the nuances of the HEC-RAS data format. However, for the purposes of RRASSLER’s downstream use cases, we make a distinction in the “orientation” of how to track model data. The standard HEC-RAS model has a single project file that might point to many geometry files. Were our only goal to facilitate HEC-centric utilization of this data, the project would be an appropriate file level to track. However, we are also interested in making the pieces of the model data more reusable and so it becomes important to capture the distinctions in modeling surfaces that those models are intended to represent. These geometry files can point to the same space but have different cross section definitions (for instance, a pre- and post-dredge model), or they could point to an entirely different portion of the river. This is critical distinction that would be lost in a single layer.
Discussion
I am both an archivist/model creator and a RRASSLER user
You will unfortunately have to keep two copies of the data. RRASSLER isn’t creating anything you don’t already have in the archive in one form or another, and completely removes all metadata and formatting that your archive has so painstakingly created. Don’t change your workflow, consider RRASSLER a “post-processing” step to your archiving work, whose primary purpose is to make a selection of your models more amenable to operational deployments.
Unit testing
The RRASSLER tutorials are a great end-to-end unit test of the sample data in the repo, but a more verbose walk through of the processing steps and touching points can be found here.
Limitations
Aligning the different model surfaces is hard. Although every effort was made to account for standard edge cases and unit cohesion, you will, more often than not, find that a surface you use and a model do not align. That is not particularly surprising, but it is often disconcerting. 3DEP timestamps, resolutions, and even order of reprojection operations may alter the surfaces slightly, even if they are stated to have come from the same input database. Do your own sanity checks and try not to lose your mind, it’s probably easier to go out and measure it again. Finally, this was developed, tested, and deployed over primarily 1D data. Although 2D model may appear to ingest correctly, there was no consideration for those in either parsing or processing, and is not accounting or copying .tif files so the value of these models within the RRASSLER workflow is greatly diminished.
Getting involved
If you have questions, concerns, bug reports, etc, please file an issue in this repository’s Issue Tracker. I know we are not the only ones attempting to align the world. General instructions on how to contribute can be found at CONTRIBUTING. More specifically, the following are known shortcomings and next steps.
A few next steps
Hardening and extention
I code out of necessity, not out of love, and I’ve been told my more than a few that I write awful code. More than half of the community will also think this is written in the wrong language. Efforts to harden the workflow and algorithm, extend this workflow into your language of choice, and general improvements would all be uses of time. For example, how multi-river models are extracted are still unclear.
RRASSTAC
Although not the most obvious use of STAC, or SpatioTemporal Asset Catalog, HEC-RAS models (most easily the footprints generated in the cataloging of the models) has been extended to the STAC framework as a STAC Item, and by that analogy each version of the catalog is a STAC collection. Formalizing this, most likely through an additional function such as STAC_catalog.R, which would generate the needed json’s and then appropriately serve those, would be a worthy task to undertake. The obvious extension of that, exposing the model cross sections with XYZ LINESTRING geometry as STAC items, is in theory what RRASSLER is accomplishing, but the framework and analogous STAC deployment is less clear and could also be explored. Some of the early attempts at this can be found in (Lawler et al. 2025)
| RRASSLER | STAC |
|---|---|
| RAS Catalog | Collection |
| Record | Item |
| Model Pieces | Assets |
2D RRASSLER
Many of the same considerations, concerns, and hurdles experienced working with and manipulating 1D RAS data will be encountered as we move into 2D model accounting. While many of the technical advancements and standards make the accounting of 2D models a bit more theoretically straightforward; since most valuable and standardized 2D models come with an associated .tif file which is footprintable, and new model formats are provided as .HDF, which has cloud compatible characteristics and is being developed, the actual work of constructing the utility which would account for those models needs to be done. There are some preliminary discussions along that particular thrust here.
Dependencies
Beyond the package dependencies listed in the description file here, this is an R package and so a more recent version of R and RStudio is needed and recommended respectively in order to capitalize on the capabilities of this repository. This was written, tested, and packaged using using a modified rocker-versioned2 environment. Typically deployed via package installation on an RStudio instance and alongside a RAS2FIM conda environment in Windows.
Open source licensing info
Credits and references
Credit to the packages used in the development, testing, and deployment of RRASSLER including but not exclusive of the packages currently listed in the DESCRIPTON file. We are appreciative of the FEMA region 6 group and the BLE data they make publicly available. Built copying patterns from RAS2FIM.
For questions
Jim Coll (FIM Developer), Fernando Salas (Director, OWP Geospatial Intelligence Division)
References
Goodell, Christopher. n.d. Breaking the HEC-RAS Code: A User’s Guide to Automating HEC-RAS.
Lawler, Seth, Thomas Williams, William Lehman, Christina Lindemer, David Rosa, Celso Ferreira, and Chen Zhang. 2025. “Evaluation of the SpatioTemporal Asset Catalog for Management and Discovery of FAIR Flood Hazard Models.” Environmental Modelling & Software 183 (January): 106230. https://doi.org/10.1016/j.envsoft.2024.106230.