{
"cells": [
{
"cell_type": "markdown",
"id": "ca315e56",
"metadata": {},
"source": [
"# Oklahoma severe-weather reports, May 2024\n",
"\n",
"Storm Events support is **available since v0.8**. This notebook downloads one complete annual NCEI **event-details** archive (about 13 MB compressed for 2024), opens the gzip CSV locally, and selects Oklahoma reports beginning in May. We compare recorded tornado, hail, and thunderstorm-wind events and inspect the tornado damage ratings.\n",
"\n",
"This is a description of archived reports, not a forecast, risk ranking, or count of distinct storms. An episode can have many events, and a tornado can cross counties and generate multiple event records. Archive revisions can change saved results. The separate locations and individual-fatality tables are outside this adapter's scope.\n",
"\n",
"Run `just notebooks` from the repository root. The first run needs internet access. Keep the manifest, generated lockfile, and cached source bytes together for reproducibility."
]
},
{
"cell_type": "code",
"execution_count": 1,
"id": "840afc0c",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Executed UTC: 2026-09-09T00:31:23.262021+00:00\n",
"Versions: {'Python': '3.14.3', 'usdata': '0.7.0', 'pandas': '3.0.5', 'matplotlib': '3.11.1'}\n"
]
}
],
"source": [
"import platform\n",
"from datetime import UTC, datetime\n",
"from pathlib import Path\n",
"\n",
"import matplotlib\n",
"import matplotlib.pyplot as plt\n",
"import pandas as pd\n",
"\n",
"import usdata\n",
"from usdata.cache import sha256_file\n",
"from usdata.pull import pull, verify\n",
"\n",
"folder = Path.cwd()\n",
"if not (folder / \"dataset.yaml\").exists():\n",
" folder = folder / \"examples\" / \"storm-events\"\n",
"manifest = folder / \"dataset.yaml\"\n",
"assert manifest.is_file(), \"Run from the notebook folder or repository root\"\n",
"print(\"Executed UTC:\", datetime.now(UTC).isoformat())\n",
"print(\n",
" \"Versions:\",\n",
" {\n",
" \"Python\": platform.python_version(),\n",
" \"usdata\": usdata.__version__,\n",
" \"pandas\": pd.__version__,\n",
" \"matplotlib\": matplotlib.__version__,\n",
" },\n",
")"
]
},
{
"cell_type": "markdown",
"id": "84dc161c",
"metadata": {},
"source": [
"## Resolve and pin the source archive\n",
"\n",
"The query touches May 2024, but the adapter selects **all of the 2024 file**, including all states and event types. Geographic and variable selectors are rejected; filtering belongs in the analysis. The newest supported creation-date filename is selected when resolving. Subsequent `pull` calls use the exact filename and checksum in the lockfile, without consulting the directory again. Historical files can be revised or removed upstream; a lockfile detects changed bytes but cannot guarantee old downloads remain available."
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "932166b1",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Archive: StormEvents_details-ftp_v1.0_d2024_c20260728.csv.gz\n",
"Compressed bytes: 12693243\n",
"Nominal file year: 2024\n",
"Source URL: https://www.ncei.noaa.gov/pub/data/swdi/stormevents/csvfiles/StormEvents_details-ftp_v1.0_d2024_c20260728.csv.gz\n",
"Retrieved UTC: 2026-09-09T00:31:36.336422+00:00\n",
"SHA-256: sha256:2070b83eccab041b36360ab73645b9a249c3eefc5b92b5b3fc0cbba4d9fcc09c\n"
]
}
],
"source": [
"result = pull(manifest)\n",
"(item,) = result.fetched\n",
"print(\"Archive:\", item.asset.id)\n",
"print(\"Compressed bytes:\", item.provenance.size)\n",
"print(\"Nominal file year:\", item.asset.time.start.year)\n",
"print(\"Source URL:\", item.provenance.source_url)\n",
"print(\"Retrieved UTC:\", item.provenance.retrieved_at.isoformat())\n",
"print(\"SHA-256:\", item.provenance.checksum)\n",
"assert item.path.read_bytes()[:2] == b\"\\x1f\\x8b\"\n",
"source_checksum = sha256_file(item.path)"
]
},
{
"cell_type": "markdown",
"id": "b6486a43",
"metadata": {},
"source": [
"## Open locally and filter by reported civil date\n",
"\n",
"`open()` decompresses in memory through a local stream; the cached file and its checksum remain compressed and unchanged. Identifier columns retain their source strings. We construct the begin **calendar date** from numeric year/month/day fields, avoiding ambiguous two-digit dates. These are reported local dates; this notebook makes no conversion to UTC. `CZ_TIMEZONE` needs separate attention when comparing precise event instants across regions."
]
},
{
"cell_type": "code",
"execution_count": 3,
"id": "c97134b1",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Rows in annual details archive: 69801\n",
"Rows with unparseable begin date: 0\n",
"Selected records: 589 distinct EVENT_ID: 589\n",
"Recorded time-zone labels: ['CST-6']\n",
"Identifier dtypes: {'EVENT_ID': 'string', 'EPISODE_ID': 'string', 'STATE_FIPS': 'string', 'CZ_FIPS': 'string'}\n"
]
},
{
"data": {
"text/html": [
"\n",
"\n",
"
\n",
" \n",
" \n",
" | \n",
" EVENT_ID | \n",
" BEGIN_DATE | \n",
" EVENT_TYPE | \n",
" CZ_TYPE | \n",
" CZ_FIPS | \n",
" TOR_F_SCALE | \n",
"
\n",
" \n",
" \n",
" \n",
" | 256 | \n",
" 1178562 | \n",
" 2024-05-06 | \n",
" Hail | \n",
" C | \n",
" 81 | \n",
" NaN | \n",
"
\n",
" \n",
" | 15716 | \n",
" 1222698 | \n",
" 2024-05-06 | \n",
" Thunderstorm Wind | \n",
" C | \n",
" 73 | \n",
" NaN | \n",
"
\n",
" \n",
" | 16029 | \n",
" 1222697 | \n",
" 2024-05-06 | \n",
" Thunderstorm Wind | \n",
" C | \n",
" 103 | \n",
" NaN | \n",
"
\n",
" \n",
" | 16743 | \n",
" 1222699 | \n",
" 2024-05-06 | \n",
" Thunderstorm Wind | \n",
" C | \n",
" 73 | \n",
" NaN | \n",
"
\n",
" \n",
" | 16744 | \n",
" 1222700 | \n",
" 2024-05-19 | \n",
" Thunderstorm Wind | \n",
" C | \n",
" 39 | \n",
" NaN | \n",
"
\n",
" \n",
" | 17577 | \n",
" 1222696 | \n",
" 2024-05-06 | \n",
" Thunderstorm Wind | \n",
" C | \n",
" 47 | \n",
" NaN | \n",
"
\n",
" \n",
" | 17649 | \n",
" 1222701 | \n",
" 2024-05-25 | \n",
" Thunderstorm Wind | \n",
" C | \n",
" 47 | \n",
" NaN | \n",
"
\n",
" \n",
" | 17752 | \n",
" 1183460 | \n",
" 2024-05-25 | \n",
" Thunderstorm Wind | \n",
" C | \n",
" 131 | \n",
" NaN | \n",
"
\n",
" \n",
"
\n",
"