ksmesopy

Python package for downloading and processing data from the Kansas Mesonet, an environmental monitoring network operated by Kansas State University.

Installation

pip install ksmesopy
pip install "ksmesopy[app]"  # Use this to also install a GUI

Dependencies: numpy, pandas, matplotlib. The desktop app additionally requires guile>=1.0.0,<2.

Quick start

import ksmesopy as ms

# Download daily temperature and precipitation for one station
df = ms.request_data(
    station="Manhattan",
    start="2024-01-01",
    end="2024-12-31",
    interval="day",
    variables=["TEMP2MAVG", "TEMP2MMIN", "TEMP2MMAX", "PRECIP"],
    verbose=True,   # print progress while downloading (default False)
)

# Optional: rename columns to snake_case
df = ms.rename_columns(df)
# TIMESTAMP → timestamp, TEMP2MAVG → tair_2m_avg, PRECIP → precip, …

# Snapshot: every station at a single time step
snap = ms.request_snapshot(
    timestamp="2025-01-01",   # for 5min/hour, include a time e.g. "2025-01-01 14:30"
    interval="day",
    variables=["TEMP2MAVG", "PRECIP"],
)
# TIMESTAMP, STATION, TEMP2MAVG, PRECIP — one row per station

Desktop app

Run this in your terminal

ksmesopy-app

A GUI for selecting stations, date ranges, variables, and intervals. Use the left navigation rail to switch between Inputs, Table, and Chart. Exports data to CSV and charts as PNG. The app ships with the Python package and runs directly without compilation; you can also launch it with python -m ksmesopy.app.

API reference

Stations

Data retrieval

Soil processing

Derived variables

Reference evapotranspiration

Both return ETo (mm day⁻¹) as an ndarray. Use extraterrestrial_radiation(doy, lat) if you also need Ra.

Atmospheric helpers

All functions accept scalars or NumPy arrays.

Charts

Each function draws onto a Matplotlib Axes supplied by the caller, so panels compose freely inside any figure layout. All functions accept API column names (TEMP2MAVG) or snake_case names (tair_2m_avg) interchangeably, and return the axes they drew on so they can be further customised.

import matplotlib.pyplot as plt
import ksmesopy as ms

fig, axes = plt.subplots(5, 1, sharex=True, figsize=(12, 14))

ms.plot_temperature(axes[0], df, ["TEMP2MAVG", "TEMP2MMIN", "TEMP2MMAX"])
ms.plot_precip(axes[1], df, "PRECIP")
ms.plot_humidity(axes[2], df, "RELHUM2MAVG")
ms.plot_solar_radiation(axes[3], df, ["SRAVG", "Ra"])  # Ra drawn dashed
ms.plot_vwc(axes[4], df)                               # auto-detects VWC columns

plt.tight_layout()
plt.savefig("meteogram.png", dpi=150)

All functions accept API column names (TEMP2MAVG) or snake_case names (tair_2m_avg) interchangeably, and return the axes they drew on so they can be further customised.

Variable catalogue

Intervals: D = daily only · H = hourly and daily · A = 5-min, hourly, and daily

Atmospheric

¹ Available at 5-min and daily only (not hourly).

Soil temperature — dedicated probes

Soil — CS655 sensors

VWC note: the Mesonet API returns VWC computed by the CS655 firmware equation. Call calibrate_vwc() to replace those values with the KSU site-specific calibration. Requires SOILKA*CM and SOILEC*CM to be fetched alongside VWC*CM. Works for any subset of depths independently.

Notes

Precipitation. The Mesonet operates dual tipping-bucket rain gauges at most stations. request_data() returns both (PRECIP, PRECIP2); the desktop app merges them to the row-wise maximum automatically. For scripted use, merge manually:

df["PRECIP"] = df[["PRECIP", "PRECIP2"]].max(axis=1)
df.drop(columns="PRECIP2", inplace=True)

Daily timestamps. The Mesonet API stores each day's aggregated values at 00:00 of the following calendar day. request_data() corrects for this automatically; the returned TIMESTAMP always reflects the observation date.

Network snapshots. request_snapshot() fetches one time step for every station in a single call — handy for mapping a variable across Kansas on a given day or 5-minute mark. It's restricted to a single instant by design; for a time series at one station use request_data(). Daily snapshots use the same next-day correction as request_data(), so the two agree for any given date.

Progress reporting. Long requests are split into chunks of 3 000 records, so a multi-year download is several round trips to the API. Pass verbose=True to request_data(), request_data_multi(), or request_snapshot() to print one line per request as it is issued:

df = ms.request_data("Manhattan", "2013-01-01", "2024-12-31", "day",
                     ["TEMP2MAVG", "PRECIP"], verbose=True)

Manhattan: 2013-01-01 - 2021-03-20
Manhattan: 2021-03-21 - 2024-12-31
Manhattan: done — 4383 rows × 2 variables

Dates carry a time component for "hour" and "5min" intervals. Failed attempts are reported too, so a slow download that is quietly retrying is visible rather than looking hung. verbose defaults to False, keeping scripted use silent.

Progress messages are also sent to the ksmesopy logger at DEBUG level regardless of verbose, so an application can capture them instead of printing:

import logging
logging.basicConfig(level=logging.DEBUG)
logging.getLogger("ksmesopy").setLevel(logging.DEBUG)

Missing values. The API encodes missing observations as "M". These are converted to NaN on read. Periods before a station or sensor was installed are pre-filled with NaN rather than omitted.

License

MIT