Examples - #108
Open
JordanLaserGit wants to merge 2 commits into
Open
Conversation
JordanLaserGit
added
the
documentation
21 tasks
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new “Getting Started” guide to provide a first-time, example-driven walkthrough of running DataStreamCLI (NextGen) and links to it from the README, addressing issue #78.
Changes:
- Add
docs/GETTING_STARTED.mdwith a step-by-step sequence of runnable examples that introduce CLI arguments progressively. - Add a README “Getting started” bullet linking to the new guide.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| README.md | Adds a “Getting started” link to the new guide to improve discoverability for new users. |
| docs/GETTING_STARTED.md | Introduces a comprehensive, example-based Getting Started document covering common workflows and options. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| -n 4 | ||
| ``` | ||
|
|
||
| - **`-D PALISADE_COLORADO`** (`--DOMAIN_NAME`) — a human-readable label for the spatial domain. It's recorded in the run metadata and helps you tell runs apart later. Omit it and DataStreamCLI uses the geopackage's base filename. Adding this option does not impact the processing in anyway. |
|
|
||
| **Step 1 — grab the forcings produced by the Example 1 run** (they already match our time window): | ||
| ```bash | ||
| cp $(pwd)/data/palisade_intro/datastream-resources/ngen-forcings/*.nc $(pwd)/palisade_forcings.nc |
| ``` | ||
|
|
||
| - **`-R …/realization_rust_lstm.json`** — a realization that runs the LSTM model (the pretrained models ship inside the NGIAB container, so there's nothing extra to download). | ||
| - **`-L 025`** (`--LSTM_ENS_MEMBERS`) — run ensemble members **0, 2, and 5**. You concatenate the member indices; `-L 0` runs a single member, `-L 012345` runs all six. The index-to-model mapping is documented in [DATASTREAM_OPTIONS.md](DATASTREAM_OPTIONS.md#lstm-enesmble-member-mapping). |
Collaborator
|
will review on Monday! |
quinnylee
requested changes
Jul 27, 2026
quinnylee
left a comment
quinnylee
left a comment
Collaborator
There was a problem hiding this comment.
Looks great and is super comprehensive! Only thing is the palisade.gpkg doesn't work with current t-route. All the examples do work with a v2.2 gpkg generated from the data preprocessor.
| -e 202006210000 \ | ||
| -C NWM_RETRO_V3 \ | ||
| -d $(pwd)/data/palisade_intro \ | ||
| -g https://ciroh-community-ngen-datastream.s3.amazonaws.com/resources/v2.1_hydrofabric/geopackages/test_data/palisade.gpkg \ |
Collaborator
There was a problem hiding this comment.
I think the hydrofabric v2.1 geopackages don't work with the most recent versions of t-route
creating supernetwork connections set
terminate called after throwing an instance of 'pybind11::error_already_set'
what(): KeyError: "['waterbody'] not found in axis"
At:
/ngen/.venv/lib64/python3.11/site-packages/pandas/core/indexes/base.py(7136): drop
/ngen/.venv/lib64/python3.11/site-packages/pandas/core/generic.py(4852): _drop_axis
/ngen/.venv/lib64/python3.11/site-packages/pandas/core/generic.py(4810): drop
/ngen/.venv/lib64/python3.11/site-packages/pandas/core/frame.py(5603): drop
/ngen/.venv/lib64/python3.11/site-packages/troute/HYFeaturesNetwork.py(635): preprocess_waterbodies
/ngen/.venv/lib64/python3.11/site-packages/troute/HYFeaturesNetwork.py(328): __init__
/ngen/.venv/lib64/python3.11/site-packages/nwm_routing/__main__.py(85): main_v04
===================================================================================
= BAD TERMINATION OF ONE OF YOUR APPLICATION PROCESSES
= PID 21 RUNNING AT e9ec274e9be2
= EXIT CODE: 6
= CLEANING UP REMAINING PROCESSES
= YOU CAN IGNORE THE BELOW CLEANUP MESSAGES
===================================================================================
YOUR APPLICATION TERMINATED WITH THE EXIT STRING: Terminated (signal 15)
This typically refers to a problem with your application.
Please see the FAQ page for debugging suggestions
Collaborator
|
Needs the -g URLs swapped to a v2.2 geopackage, Rest looks good to me |
harshavemula-ua
approved these changes
Jul 30, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a Getting Started guide that walks a first-time user through a DataStreamCLI (NextGen internally) run one CLI argument at a time. Closes #78.
This guide closely mimics the 2024 and 2025 CIROH developers conference tutorials materials that are still available in this repository. This getting started guide is more detailed and will be maintained, whereas the tutorials may become outdated overtime as the tool evolves.
Additions
docs/GETTING_STARTED.mdRemovals
Changes
Testing
Screenshots
N/A — documentation only.
Notes
DATA_DIRis passed via-d(pending removal ofDATA_DIRfrom the writtendatastream.env) Remove DATA_DIR from generated .env #107.Todos
Checklist
Testing checklist
Target Environment support
Accessibility
Other