# Hydrohistorian data release: Colorado groundwater (statewide)

Built 2026-10-26T08:14:28-06:00 from HydroBase snapshot `HydroBase_CO_20260928` plus the site's daily DWR/USGS refreshes (code `23d2bd0`).
Water districts: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 47, 49, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 67, 68, 69, 70, 71, 72, 77, 78, 79, 80.

Every table ships as Parquet; the smaller ones also as one CSV, the two daily tables as one gzipped CSV per water district (some exceed a spreadsheet's 1,048,576-row limit). `streamflow_daily_wide.csv` is one row per day and one column per gage, sized for a spreadsheet. `riverware.zip` holds a RiverWare control-file DMI: one data file per gage and per structure's daily diversion, a `control.ctl` whose object/slot names you rename to your model's, and `network.csv` + `streams.csv` (every structure, gage and confluence in downstream order, from DWR's stream network). `manifest.json` lists every file with its row count and SHA-256.

## What was changed from the published record

- DWR publishes -999 for 'no measurement'. gw_levels drops those values; a missing reading is missing, never zero.
- A permit receipt is an application, not a physical well: group by permit, and expect several receipts for one hole (replacements, changes) and receipts for wells never drilled.
- Permit yields and static levels are what the driller reported at completion. Pump-test yield is capped near the permitted rate and is not an aquifer test or a transmissivity.
- Aquifer names on permits and monitoring wells are labels as filed (about 82% of monitoring wells carry none; regime then falls back to the designated basin). Formation depths come from gw_picks (geophysical picks) -- cite which one you used.
- logType is free text with no published legend (about 70 spellings). curve_families decodes only spelled-out tokens; R, C, G, D, N and other single letters are left as filed.
- The geophysical-log network is a Denver Basin instrument: about 85% of log wells are in Division 1 and 15% in Division 2; elsewhere their absence is the fact.
- Water-table trends are computed on one datum per well (elevation or depth, whichever the well reports more); denver_basin, high_plains and other bedrock declines are storage loss, not a recharge signal.
- These are public DWR records assembled by Hydrohistorian. HydroBase and DWR's Laserfiche remain the authority; every document row carries DWR's own link.
- gw_digitized: 5,514 scan pages could not be digitized automatically (older hand-filled logs, rotated or unsupported layouts); the scans themselves are in gw_documents.
- The document mirror is still filling: 8,538 of 241,806 listed documents are held so far. Every row carries DWR's own link either way.

## Tables

### gw_wells

DWR monitoring wells statewide. 34,337 rows.

| column | meaning |
|---|---|
| `well_id` | DWR monitoring well id (joins gw_levels, gw_trends) |
| `name` | Well name |
| `receipt` | Permit receipt, where linked (joins gw_permits.receipt) |
| `wdid` | WDID, where the well has one |
| `division` | Water division |
| `water_district` | Water district |
| `latitude` | Decimal degrees |
| `longitude` | Decimal degrees |
| `elevation_ft` | Land-surface elevation, feet |
| `well_depth_ft` | Well depth, feet |
| `aquifer1` | Primary aquifer as DWR records it (often blank) |
| `aquifer2` | Secondary aquifer as recorded |
| `top_perf_ft` | Top of perforated casing, feet below land surface |
| `bottom_perf_ft` | Bottom of perforated casing, feet below land surface |
| `yield_gpm` | Yield, gpm, as reported (driller/permit figure, not an aquifer test) |
| `designated_basin` | Designated ground water basin, if any |
| `regime` | alluvial | denver_basin | high_plains | san_luis_confined | other_bedrock | unknown (aquifer name first, designated basin as fallback; groundwater.aquifer_regime) |
| `setting` | alluvial | bedrock | unknown -- the site's conservative gate (groundwater.classify_well) |

### gw_levels

Water-level measurements for those wells. 1,015,652 rows (1882-12-31 to 2026-09-25).

| column | meaning |
|---|---|
| `well_id` | Joins gw_wells.well_id |
| `date` | Measurement day (America/Denver) |
| `depth_to_water_ft` | Depth to water below land surface, feet |
| `water_level_elevation_ft` | Water-level elevation, feet |

### gw_trends

Per-well water-table trends (Mann-Kendall on annual means; >=20 readings over >=10 years). 3,467 rows.

| column | meaning |
|---|---|
| `well_id` | Joins gw_wells.well_id |
| `setting` | As gw_wells.setting |
| `n` | Measurements behind the trend |
| `span_years` | Years between first and last annual mean |
| `trend` | Mann-Kendall verdict on annual mean level (increasing = water table rising) |
| `slope_ft_per_decade` | Sen's slope, feet per decade (positive = rising) |
| `p_value` | Mann-Kendall p-value |

### gw_permits

Colorado well permits (owner and contact fields are never fetched). 599,044 rows.

| column | meaning |
|---|---|
| `receipt` | Permit receipt (DWR's key; one receipt = one application, not one physical well) |
| `permit` | Permit number with suffix, e.g. 22189-F |
| `status` | Current permit status |
| `category` | Permit category |
| `uses` | Associated uses |
| `aquifers` | Associated aquifers (permit label) |
| `wdid` | WDID |
| `division` | Water division |
| `water_district` | Water district |
| `county` | County |
| `designated_basin` | Designated basin |
| `management_district` | Groundwater management district |
| `latitude` | Decimal degrees |
| `longitude` | Decimal degrees |
| `location_accuracy` | DWR's location note |
| `elevation_ft` | Land-surface elevation, feet |
| `pm` | Principal meridian |
| `township` | Township |
| `range` | Range |
| `section` | Section |
| `q10` | 10-acre quarter |
| `q40` | 40-acre quarter |
| `q160` | 160-acre quarter |
| `depth_total_ft` | Total depth, feet (as reported) |
| `top_perf_ft` | Top perforated casing, feet |
| `bottom_perf_ft` | Bottom perforated casing, feet |
| `pump_test_yield_gpm` | Driller's pump-test yield, gpm (capped near the permitted rate; not transmissivity) |
| `static_water_level_ft` | Static water level at completion, feet below land surface |
| `static_water_level_date` | Date of that level |
| `driller` | Driller |
| `date_application_received` | Date |
| `date_permit_issued` | Date |
| `date_first_beneficial_use` | Date |
| `date_permit_expires` | Date |
| `date_well_completed` | Date |
| `date_pump_installed` | Date |
| `date_well_plugged` | Date |
| `modified` | DWR's last-modified stamp |
| `dwr_url` | DWR's permit page |

### gw_log_wells

DWR's geophysical-log well index. 6,106 rows.

| column | meaning |
|---|---|
| `well_id` | DWR geophysical-log well id (joins gw_picks, gw_documents.well_id) |
| `name` | Well name |
| `receipt` | Permit receipt, where the log well has one |
| `permit` | Permit number |
| `ecmc_id` | ECMC (oil and gas) API county+sequence, where an oil/gas well |
| `log_date` | Date logged |
| `log_type_raw` | DWR's logType exactly as filed (free text; no published legend) |
| `curve_families` | Curve families read ONLY from unambiguous tokens (GR, RES, NMR...); single letters like R, C, G are left undecoded -- see log_type_raw |
| `log_top_ft` | Top of logged interval, feet |
| `log_bottom_ft` | Bottom of logged interval, feet |
| `log_swl_ft` | Static water level when logged, feet |
| `aquifer_picks` | Aquifers picked (see gw_picks) |
| `well_depth_ft` | Well depth, feet |
| `top_perf_ft` | Top perforated casing, feet |
| `bottom_perf_ft` | Bottom perforated casing, feet |
| `base_of_grout_ft` | Base of grout, feet |
| `wdid` | WDID |
| `division` | Water division |
| `water_district` | Water district |
| `county` | County |
| `designated_basin` | Designated basin |
| `management_district` | Management district |
| `pm` | Principal meridian |
| `township` | Township |
| `range` | Range |
| `section` | Section |
| `q10` | Quarter |
| `q40` | Quarter |
| `q160` | Quarter |
| `latitude` | Decimal degrees |
| `longitude` | Decimal degrees |
| `location_accuracy` | DWR's location note |
| `elevation_ft` | Land-surface elevation, feet |
| `dwr_url` | DWR's geophysical-log page |
| `ecmc_url` | ECMC well-log list (oil/gas wells) |

### gw_picks

Formation tops and bases picked from those logs. 12,716 rows.

| column | meaning |
|---|---|
| `well_id` | Joins gw_log_wells.well_id |
| `aquifer` | Aquifer/formation picked, as DWR names it (coarse ARAPAHOE and split UPPER/LOWER ARAPAHOE both occur, sometimes in one well -- never merged here) |
| `top_depth_ft` | Top, feet below land surface |
| `base_depth_ft` | Base, feet below land surface |
| `top_elev_ft` | Top elevation, feet |
| `base_elev_ft` | Base elevation, feet |
| `interval_ft` | base_depth_ft - top_depth_ft: the gross aquifer interval, feet (computed here) |
| `net_sand_ft` | DWR's gLogThickness, defined by DWR as 'Total thickness of the sand layers in aquifer (feet)' -- NET sand, smaller than interval_ft (DB-110 Arapahoe: 495 ft interval, 360 ft sand) |
| `comment` | DWR's comment |

### gw_documents

DWR documents for log wells and monitored wells: logs, LAS files and key permit papers. 241,806 rows.

| column | meaning |
|---|---|
| `doc_id` | Laserfiche document id |
| `well_id` | Log well id, where listed from a log-well page |
| `receipt` | Receipt, where listed from a receipt |
| `category` | Geophysical Log | Well Permit Information |
| `doc_type` | DWR's document type (Log, Log LAS, Well Construction, Well Yield Test Report...) |
| `pages` | Pages (scans) |
| `created` | Date DWR filed it |
| `dwr_url` | DWR's own viewer/download link |
| `mirrored` | True once Hydrohistorian holds a copy |
| `file` | Path in the document store |
| `format` | las | pdf | ... |
| `bytes` | File size |
| `sha256` | Checksum of the mirrored copy |
| `withdrawn_on` | Date our copy was withdrawn on request (/well-documents); DWR's own link still works. Blank = not withdrawn |

### gw_digitized

Curves digitized automatically from the mirrored log scans, one row per curve with its confidence gate; the LAS files are in the document store. Screening data: keep the scan. 10,121 rows.

| column | meaning |
|---|---|
| `doc_id` | The scan (joins gw_documents.doc_id) |
| `well_id` | Log well id (joins gw_log_wells) |
| `page` | Page of the scan |
| `curve` | Curve name as printed on the scan's scale header |
| `mnemonic` | Curve mnemonic in the LAS file |
| `unit` | Unit as printed |
| `scale` | linear | log, from the printed scale |
| `weight` | How the curve was told from its track-mates: thick | thin (stroke weight) | color:<name> |
| `v_left` | Printed scale value at the track's left edge |
| `v_right` | Printed scale value at the right edge |
| `depth_top_ft` | Top of the digitized interval, feet |
| `depth_base_ft` | Base, feet |
| `coverage` | Share of depth steps with a traced value |
| `ambiguous` | Share of rows where a second stroke of the same ink was present (another curve, or noise) |
| `n_wraps` | Rows where the trace jumped more than 60% of the track (a backup-scale wrap or a lost curve) |
| `labels` | OCR'd depth labels on the fitted depth axis |
| `max_resid_ft` | Worst depth-label residual, feet |
| `scale_conf` | OCR confidence of the printed scale numbers (0-1) |
| `gate` | pass | fail: the confidence gate (see the benchmark). Use pass rows; fail rows say why. digitizer-quality.json beside this release gives, per curve class, what passing curves scored against DWR's own LAS |
| `reasons` | Why the gate failed (blank on pass) |
| `las` | Path of the LAS file in the document store |
| `version` | Digitizer version (docs/research/log-digitizer-benchmark.md) |