RainbowStats™ · Command reference

USBR Reservoir Data

Discover a reservoir’s records, retrieve daily observations, and follow its water balance from inflow to release.

RainbowStats connects the Bureau of Reclamation’s RISE data catalog to its time-series and charting tools. Use it to examine reservoir storage, inflow, releases, evaporation and other available daily measurements across the western United States.

Five commands, from discovery to analysis
Command	Purpose	Returns
`USBR`	Retrieve one daily measurement, with an optional explicit date range.	Daily data series
`USBR_SEARCH`	Search the RISE catalog, optionally within a state.	Metadata table
`USBR_META`	Inspect one catalog item’s measurement, units and coverage.	Metadata table
`USBR_LOCATION_META`	Discover catalog items associated with a reservoir or site.	Metadata table
`USBR_SANKEY`	Build the supported Elephant Butte annual water-balance diagram.	Sankey chart

Quick start: discover, inspect, chart

matches = USBR_SEARCH("NM", "Elephant Butte")
details = USBR_META("4376")
inflow = USBR("4376", 20240101, 20241231)
chart = SET_TITLE(LINE_CHART(inflow), "Elephant Butte daily inflow — 2024 — acre-feet")

The search helps identify available records. Item "4376" contains daily inflow volume for Elephant Butte Reservoir. The example requests a complete calendar year and plots each day’s reported volume.

Use the RISE item ID. A reservoir can have separate items for storage, elevation, inflow and releases. Each item identifies one series. "4376" is an inflow item; "323" is Elephant Butte’s location ID, used with USBR_LOCATION_META.

USBR — Retrieve daily observations

USBR("item_id")
USBR("item_id", start_date, end_date)

Returns the selected item as a daily numeric series. The one-argument form requests January 1, 2000 through the current date. Supply explicit dates for earlier history or a fixed analysis window. Requests are limited to the item’s available period of record; recent observations may lag today.

Argument	Description
`item_id`	Quoted numeric RISE catalog item ID, such as `"329"` for Elephant Butte storage. It is not a USGS station number, RISE parameter ID or catalog record ID.
`start_date`	Inclusive start date, supplied as `YYYYMMDD` or a quoted ISO date such as `"2024-01-01"`.
`end_date`	Inclusive end date in the same supported formats. It must be on or after the start date.

storage = USBR("329")
long_history = USBR("329", 19860101, 20241231)
inflow = USBR("4376", "2024-01-01", "2024-12-31")
releases = USBR("4378", 20240101, 20241231)

Daily storage is an inventory observed at a point in time. Daily inflow and release volumes are movements of water over a day. Both may use acre-feet, but they have different meanings. Check the item’s aggregation as well as its units.

The retrieval command supports daily operational time-series items. Search results may also contain monthly records, modeled series and documents; inspect metadata before requesting them. Modeled items require model-run selection and are not supported by this command.

USBR_SEARCH — Find reservoirs and measurements

USBR_SEARCH("search_text")
USBR_SEARCH("state", "search_text")

Searches the RISE catalog and returns a table of matching catalog items. Search by reservoir name or other descriptive text. The two-argument form restricts the search to a state.

elephant_butte = USBR_SEARCH("Elephant Butte")
new_mexico = USBR_SEARCH("NM", "Elephant Butte")
shasta = USBR_SEARCH("CA", "Shasta")
powell = USBR_SEARCH("Lake Powell")

Use state postal abbreviations. "NM" means New Mexico and "CA" means California. USBR search uses postal abbreviations, unlike the state FIPS codes used by USGS_SEARCH.

A match can bring back multiple related items from a catalog record. Check each item’s title, units, frequency, aggregation and modeled status. A reservoir-name match does not guarantee that every listed item is a usable daily water series.

USBR_META — Inspect one measurement

details = USBR_META("4376")

Returns a metadata table for one RISE item. Use it to confirm what the series measures and whether its coverage and units suit the analysis.

Metadata field	What it tells you
`item_id` / `title`	The series identifier and descriptive title.
`parameter`	The measurement, such as reservoir storage, inflow or total release.
`units`	Reported units, such as `af` (acre-feet), `cfs` (cubic feet per second) or `ft`.
`frequency`	The observation interval. Look for `daily` for use with `USBR`.
`aggregation`	How the value represents the interval: for example, `instant`, `average` or `sum`.
`begin` / `end`	The item’s reported period of record, which can extend beyond the default requested range.
`modeled`	Whether the catalog identifies the item as modeled.

Additional source attributes are included when available, such as descriptions, disclaimers, update information and location identifiers. Available columns can vary between items.

USBR_LOCATION_META — Explore a reservoir’s records

site_details = USBR_LOCATION_META("323")

Lists the catalog items linked to one RISE location. For Elephant Butte, location "323" provides a way to discover storage, inflow, release, evaporation and other associated items.

Copy an item ID from this table into USBR_META or USBR. Keep the identifier types separate: the location identifies the site, a catalog record groups related content, and an item identifies the particular dataset.

Useful reservoir item IDs

These operational items provide starting points for the four-reservoir example. Units and availability differ by reservoir; confirm them with USBR_META before combining series.

Reservoir	Storage · af	Inflow	Total release	Evaporation
Elephant Butte	`329`	`4376` · af/day	`4378` · af/day	`333` · af/day
Lake Powell	`509`	`4288` · af/day	`4354` · af/day	`510` · af/day
Lake Mead	`6124`	Not in the selected operations record	`6122` · af/day	Not in the selected operations record
Shasta	`10864`	`10867` · cfs	`10869` · cfs	`10861` · cfs

Here, af/day describes an acre-foot volume reported for each day; RISE labels these volume items with units af and aggregation sum. Storage items are instantaneous acre-foot inventories. Shasta’s evaporation export uses cfs with an aggregation label of sum; interpret it using the daily operations documentation.

Use Powell’s operational inflow item 4288 for this balance. The separately published unregulated-inflow estimate answers a different question. Shasta’s full-natural-flow series is also distinct from reservoir inflow.

Examples: storage histories and cumulative flows

Chart a long storage history

storage = USBR("329", 19860101, 20241231)
storage_maf = SET_UNITS(SET_NAME(storage/1000000, "Elephant Butte storage"), "million acre-feet")
chart = SET_TITLE(LINE_CHART(storage_maf), "Elephant Butte storage — 1986–2024")

Compare cumulative inflow and releases

inflow = USBR("4376", 20240101, 20241231)
releases = USBR("4378", 20240101, 20241231)
cum_inflow = SET_NAME(CUM_SUM(inflow), "Cumulative inflow — acre-feet")
cum_releases = SET_NAME(CUM_SUM(releases), "Cumulative releases — acre-feet")
chart = SET_TITLE(LINE_CHART(cum_inflow, cum_releases), "Elephant Butte cumulative flows — calendar 2024")

Cumulative sums are appropriate for daily flow volumes. Summing daily storage would count the same stored water repeatedly. For a daily mean rate in cfs, first convert each daily observation to acre-feet:

daily_rate = USBR("10869", 20240101, 20241231)
daily_volume = SET_UNITS(daily_rate*(86400/43560), "acre-feet")
annual_volume = END_VALUE(CUM_SUM(daily_volume))

One cfs sustained over a day equals approximately 1.98347 acre-feet. The annual sum is meaningful only when all required daily observations are present. Do not use a simple annual average as an annual volume.

USBR_SANKEY — Follow an annual water balance

budget = USBR_SANKEY(2024)

Builds an annual Elephant Butte Reservoir Sankey chart. Supply an integer calendar year. This convenience command currently targets Elephant Butte; it is not a reservoir-name selector.

The reservoir diagram connects inflow and any storage draw to releases, evaporation and any storage gain. A remaining mismatch is shown as an unreconciled balance. The helper requires complete daily flow coverage and the storage observations needed to calculate the year’s change.

Calendar-year accounting. The diagram covers January 1 through December 31. It uses the preceding December 31 storage observation as the opening inventory. A storage-change branch represents the amount gained or drawn during the year, not the reservoir’s total contents.

The 2024 downstream extension

For 2024, the chart continues from Elephant Butte releases through Caballo delivery accounting to the reported New Mexico, Texas and Mexico delivery charges. This extension uses figures from Reclamation’s 2024 report to the Rio Grande Compact Commission. Other years retain the reservoir-only balance unless corresponding downstream accounting has been added.

Delivery charges are administrative water accounts. They do not directly measure agricultural consumption. Inter-reservoir and downstream differences remain accounting balances rather than being automatically assigned to evaporation or seepage. The 2024 extension uses the listed delivery components; their sum differs from the report’s printed total by 96 acre-feet.

Combine text, a flow chart and the Sankey

intro = TEXT_SLIDE("Elephant Butte water balance", "Daily USBR records show inflow, releases, evaporation and the change in stored water.", "The 2024 Sankey extends to downstream delivery accounts; those charges are not a measure of crop consumption.")
inflow = USBR("4376", 20240101, 20241231)
releases = USBR("4378", 20240101, 20241231)
inflow_named = SET_NAME(inflow, "Daily inflow — acre-feet")
releases_named = SET_NAME(releases, "Daily releases — acre-feet")
flows = SET_TITLE(LINE_CHART(inflow_named, releases_named), "Elephant Butte daily flows — 2024")
budget = USBR_SANKEY(2024)
presentation = SLIDESHOW(intro, flows, budget)

Other reservoirs

Use their daily series with the general SANKEY_LINK, SANKEY_PATH, SANKEY_GROUP and SANKEY_CHART commands to construct a custom balance. Keep all link values in the same volume units and accounting period. In the four-reservoir example, Mead’s missing inflow and evaporation records are handled with a clearly labeled inferred net input, not a measured gross inflow.

Open the working four-reservoir slideshow: Elephant Butte, Powell, Mead and Shasta.

Working with the data

Read units and aggregation together. An instantaneous inventory, an average flow rate and a daily flow volume cannot be combined without interpreting and converting them correctly.
Missing is not zero. Missing numeric observations are omitted; reported zeros and valid negative values are retained. Check complete coverage before computing an annual total.
Use consistent boundaries. Calendar years and water years differ. To calculate annual storage change, include both the prior year-end and current year-end inventory.
Computed inflow is not an independent gauge measurement. Some operating records derive inflow from storage change, releases and other terms. A small residual can partly reflect how the source was constructed.
Keep accounting balances visible. Unmeasured inflows, bank storage, omitted diversions, rounding, revisions and timing differences may affect closure. A mismatch is not automatically a physical loss.
Agricultural use needs additional records. Releases and delivery charges alone do not identify crop consumption. Choose between gross diversions, delivered water and consumptive use before estimating a sector share.
Connected reservoirs share water. Powell releases and Mead inflows cannot be added as independent supplies.
Recent data can change. Reclamation identifies data as provisional unless otherwise noted. Check item descriptions and disclaimers.
Long histories take longer initially. Retrieval uses annual download chunks and cached source responses. The first request for several decades can take more time than a repeat request.

Data sources and further reading

Source: U.S. Bureau of Reclamation, Reclamation Information Sharing Environment (RISE). RainbowStats retrieves daily CSV observations and catalog metadata from RISE.