AEGIS Reference Dataset v1.0

Overview

The AEGIS Reference Dataset v1.0 contains the hourly streamflow records, signal-clarity metrics, and runoff events used to evaluate the Automated Event & HydroGraph Identification Strategy (AEGIS). The release covers 195 U.S. Geological Survey (USGS) gauges in five states and includes 9,605 detected events.

AEGIS Reference Dataset v1.0 is intended for reproducible hydrograph-identification research, comparison of event timing and shape among gauges, and evaluation of streamflow records before event extraction.

Release summary

The timestamps above are the first and last timestamps present in every processed streamflow file. They correspond approximately to the 2003-2023 period in the gauges' local standard-time zones.

Directory structure

text AEGIS_Reference_Dataset_v1.0/ |-- README.md |-- LICENSE.md |-- CITATION.cff |-- data_dictionary.csv |-- station_inventory.csv |-- q_processed/ | |-- README.md | `-- USGS_<gauge_id>_processed_streamflow.csv (195 files) |-- detected_events/ | |-- README.md | `-- USGS_<gauge_id>_detected_events.csv (195 files) `-- signal_clarity/ |-- README.md `-- signal_clarity.csv

Supporting metadata

• data_dictionary.csv consolidates the schemas, data types, units, missing-value conventions, observed or allowed values, and provenance notes for all released tables.
• station_inventory.csv provides one row per gauge with the verified identifier, station name, state, NAD83 coordinates, drainage area in square kilometers, and relative paths to the corresponding processed-streamflow and detected-event files.

Gauge identifiers in both metadata files are text values; leading zeroes are significant.

q_processed/

Each gauge file contains a continuous hourly time axis and the following columns:

detected_events/

Each gauge file contains the samples assigned to detected events:

Event identifiers are local to a gauge file and are not globally unique. A globally unique key can be formed from the USGS gauge identifier and event_id.

signal_clarity/

signal_clarity.csv contains one row per gauge, station identifiers and attributes, and the S1, S2, and S4 signal-clarity metrics. The number denotes the rolling-window length in weeks. Larger values indicate that short-window variability constitutes a larger fraction of the full-record variability; in this study, S4 values near or above 0.5 identified records that may require additional event-detection parameter tuning.

Each data directory includes a README with its file-naming convention and variable dictionary.

Data provenance

The source observations are USGS instantaneous discharge records (USGS parameter code 00060, discharge in cubic feet per second) from the National Water Information System. The original readings were generally recorded at 15-minute intervals. USGS notes that instantaneous records are commonly collected every 15 minutes, although availability and approval status can vary by site and date.

• USGS Instantaneous Values service documentation: https://nwis.waterservices.usgs.gov/docs/instantaneous-values/
• USGS Instantaneous Values service details: https://nwis.waterservices.usgs.gov/docs/instantaneous-values/instantaneous-values-details/
• USGS Water Data for the Nation: https://waterdata.usgs.gov/

The data-retrieval date was not retained in the exported AEGIS Reference Dataset v1.0 files. Users requiring the exact USGS revision state should treat AEGIS Reference Dataset v1.0 as the authoritative study snapshot rather than expect a new service query to reproduce every value exactly.

Processing and event-identification methods

The study began with 343 candidate gauges in three broad CONUS study regions: the Carolinas, Texas, and Florida-Georgia-Alabama. Gauges with at least 70% record completeness were retained, resulting in the 195-gauge release.

Processing proceeded as follows:

1. Fifteen-minute streamflow observations were quality-controlled for continuity and resampled to one hour by retaining the maximum discharge in each hour.
2. For each gauge, hourly discharge was normalized by the mean of its UTC calendar-year maximum discharges. The year-end grouping was applied to the complete exported UTC index; consequently, the final five hours on 2024-01-01 form a partial 2024 bin:

text normalized_streamflow(t) = streamflow(t) / mean(annual maximum streamflow)

1. Signal clarity was calculated as the median rolling sample standard deviation divided by the sample standard deviation of the complete normalized series. Rolling windows of 1, 2, and 4 weeks produced S1, S2, and S4, respectively.
2. AEGIS separated direct runoff from baseflow using the Nathan-McMahon recursive digital filter. The study configuration used filter parameter 0.995, runoff threshold 0.01, event threshold 0.5, maximum missing fraction 0.2, and minimum peakness 0.6.
3. Positive-runoff periods were identified after thresholding. Candidate event windows were retained only when they met the normalized-flow, missing-data, and peakness criteria. The exported event files contain the normalized total streamflow samples for the retained windows.

The event boundaries and values in this release should be used as the fixed AEGIS Reference Dataset v1.0 results. Re-running a later AEGIS version or changing any parameter can produce different events.

Basic use

Preserve gauge identifiers as text because leading zeroes are significant.

```python from pathlib import Path import pandas as pd

root = Path("AEGIS_Reference_Dataset_v1.0") gauge_id = "02085000"

streamflow = pd.read_csv( root / "q_processed" / f"USGS_{gauge_id}_processed_streamflow.csv", parse_dates=["datetime_utc"], na_values={"streamflow_cfs": ["-9999.00"]}, )

events = pd.read_csv( root / "detected_events" / f"USGS_{gauge_id}_detected_events.csv", parse_dates=["datetime_utc"], dtype={"event_id": "int64"}, )

stations = pd.read_csv( root / "signal_clarity" / "signal_clarity.csv", dtype={"USGS_Gauge_ID": "string"}, ) ```

Quality and interpretation notes

• Source records may contain gaps. In streamflow_cfs, -9999.00 represents missing discharge and must not be interpreted as a physical negative flow or as zero.
• At discharge-gap hours, normalized_streamflow is retained as a linearly interpolated value used by the event-identification workflow; it is not a direct observation for that hour.
• streamflow_cfs is an hourly maximum, not an hourly mean or instantaneous value at the top of the hour.
• normalized_streamflow and qz are dimensionless total-streamflow values, not the filter-derived direct-runoff component.
• event_id values restart at 1 for each gauge.
• Signal-clarity metrics are screening indicators, not universal pass/fail classifications. High-S4 records may still be usable after inspecting the hydrographs and tuning AEGIS.
• Station attributes and USGS observations can be revised by their source agency. AEGIS Reference Dataset v1.0 preserves the values used for the associated study.

Related software and manuscript

• AEGIS source code: https://github.com/jjguerrerog/AEGIS
• Local study revision: b8e6b67021ecbb5dcd9fc1529c70e1fc687eec47
• Associated manuscript: Juan Guerrero-Gallego and Nicolas Velasquez Giron, AEGIS: An Automated Event & Hydrograph Identification Strategy (manuscript in preparation).

The AEGIS software repository is licensed under GNU GPL v3. That software license does not by itself license the AEGIS Reference Dataset v1.0 data.

Authors and contact

• Juan Guerrero-Gallego, Department of Mechanical and Civil Engineering, Florida Institute of Technology
• Nicolas Velasquez Giron, Department of Mechanical and Civil Engineering, Florida Institute of Technology
• Corresponding contact: Juan Guerrero-Gallego, jguerrerogal2024@my.fit.edu

Citation

Until a repository DOI is assigned, cite the dataset as:

Guerrero-Gallego, J., & Velasquez Giron, N. (2026). AEGIS Reference Dataset, version 1.0 [Data set]. Florida Institute of Technology.

Machine-readable provisional citation metadata are provided in CITATION.cff. The ORCID lines are intentionally commented placeholders and can be activated after the authors insert their verified ORCID URLs. Release date, DOI, and HydroShare repository fields are likewise commented until those identifiers exist.

Also cite the associated AEGIS manuscript when it becomes available. Replace the provisional citation above with the repository-generated citation and DOI in publications prepared after archival release.

License

AEGIS Reference Dataset v1.0 is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0). Users may share and adapt the material for any purpose, including commercially, provided that appropriate credit is given, the license is linked, and changes are indicated. See LICENSE.md for the complete dataset license notice.

This license applies to the AEGIS Reference Dataset v1.0 compilation, derived products, organization, and original documentation to the extent that copyright or database rights exist. Underlying USGS observations remain public-domain U.S. government data and should continue to be acknowledged as the source.