ksmesopy 0.2.0

Python API for the Kansas Mesonet

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.

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"],
)

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

Desktop app

Run this in your terminal

ksmesopy-app

A GUI for selecting stations, date ranges, variables, and intervals, with a tabular view and time-series chart. Exports to CSV and PNG.

---

API reference

Stations

Function	Returns	Description
get_stations()	DataFrame	Full station metadata table
get_stations(names_only=True)	list[str]	Sorted list of station names only
get_stations_active()	DataFrame	Availability table: STATION, OBS_INTERVAL (s), START, END

Data retrieval

Function	Returns	Description
request_data(station, start, end, interval, variables, *, verbose, sleep)	DataFrame	Download data for one station. interval is "day", "hour", or "5min". Daily timestamps are corrected from the Mesonet's next-day convention.
request_data_multi(stations, start, end, interval, variables, *, verbose, sleep)	dict[str, DataFrame]	Same as above for a list of stations; returns one DataFrame per station.
list_variables(interval=None)	list[dict]	Variable catalogue filtered by interval, or all variables if None. Each entry has keys api_name, snake_name, description, intervals.
rename_columns(df, preset="snake")	DataFrame	Rename API column names to snake_case (e.g. TEMP2MAVG → tair_2m_avg). Pass a dict for a custom mapping.

Soil processing

Function	Returns	Description
calibrate_vwc(df, vwc_cols=None)	DataFrame	Replace firmware VWC values with the KSU site-specific calibration. Requires SOILKA*CM and SOILEC*CM columns. Works on any subset of depths.
compute_soil_water_storage(df)	DataFrame	Trapezoidal soil water storage in the top 50 cm (mm). Requires all four VWC depths; adds a STORAGE_MM column. Call calibrate_vwc() first for calibrated storage.

Derived variables

Function	Returns	Description
growing_degree_days(tmin, tmax, base=10.0, ceiling=30.0)	ndarray	Daily GDD. Both tmin/tmax clipped to [base, ceiling] before averaging.
heat_index(temp, rh)	ndarray	NOAA/NWS apparent temperature (°C).
wind_chill(temp, wspd)	ndarray	NWS wind chill (°C); valid for temp ≤ 10 °C, wind ≥ 1.3 m s⁻¹.
temperature_humidity_index(temp, rh)	ndarray	THI for livestock heat stress. Thresholds (dairy): <68 none · 68–72 mild · 72–80 moderate · 80–90 severe · >90 dangerous.

Reference evapotranspiration

Function	Returns	Description
reference_et_penman_monteith(doy, lat, elev, tmin, tmax, srad, wspd, rhmin, rhmax, *, vpd, ea, wind_height)	ndarray	FAO-56 Penman-Monteith. Supply vapour pressure via ea=, vpd=, or rhmin=+rhmax=. srad in W m⁻², converted internally.
reference_et_hargreaves(doy, lat, tmin, tmax, *, tmean)	ndarray	Hargreaves–Samani. Temperature only — no humidity, radiation, or wind needed.

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

Atmospheric helpers

Function	Output
saturation_vapor_pressure(temp)	es (kPa)
actual_vapor_pressure(temp, rh)	ea (kPa)
vapor_pressure_deficit(temp, rh)	VPD (kPa, ≥ 0)
slope_saturation_vapor_pressure(temp)	Δ (kPa °C⁻¹)
atmospheric_pressure(elev)	P (kPa)
psychrometric_constant(elev)	γ (kPa °C⁻¹)
extraterrestrial_radiation(doy, lat)	Ra (MJ m⁻² day⁻¹)
net_radiation(srad_mj, tmin, tmax, ea, elev, doy, lat)	Rn (MJ m⁻² day⁻¹)
srad_to_mj(srad, period)	energy (MJ m⁻²)

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.

Function	Key behaviour
plot_temperature(ax, df, variables, *, band, ylabel, legend)	Shaded band when min/avg/max triplet detected (band=True); plain lines otherwise. Works for air and soil temperature.
plot_precip(ax, df, variable, *, ylabel, color)	Bar chart, bar width inferred from timestamp spacing.
plot_humidity(ax, df, variables, *, ylabel, legend)	Lines, y-axis fixed 0–100 %.
plot_vpd(ax, df, variables, *, ylabel, legend)	Filled area + line, y-axis starts at 0.
plot_solar_radiation(ax, df, variables, *, ylabel, legend)	Filled area for observed; dashed line for Ra columns (detected by name).
plot_wind(ax, df, speed, direction, *, ylabel, legend)	Speed as line; direction overlaid as scatter on a twin y-axis with N/E/S/W ticks.
plot_vwc(ax, df, variables, *, ylabel, legend)	Sequential colormap shallow→deep; auto-detects VWC columns if variables=None.
plot_et(ax, df, variables, *, bar, ylabel, legend)	Line by default; bar=True for daily totals.

---

Variable catalogue

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

Atmospheric

API name	snake_case	Description	Unit	Intervals
TEMP2MAVG	tair_2m_avg	Air temperature 2 m avg	°C	A
TEMP2MMIN	tair_2m_min	Air temperature 2 m min	°C	D
TEMP2MMAX	tair_2m_max	Air temperature 2 m max	°C	D
TEMP10MAVG	tair_10m_avg	Air temperature 10 m avg	°C	A
TEMP10MMIN	tair_10m_min	Air temperature 10 m min	°C	D
TEMP10MMAX	tair_10m_max	Air temperature 10 m max	°C	D
RELHUM2MAVG	rh_2m_avg	Relative humidity 2 m avg	%	A
RELHUM2MMIN	rh_2m_min	Relative humidity 2 m min	%	D
RELHUM2MMAX	rh_2m_max	Relative humidity 2 m max	%	D
VPDEFAVG	vpd_avg	Vapor pressure deficit avg	kPa	A
PRESSUREAVG	pressure_avg	Atmospheric pressure avg	kPa	A
PRECIP	precip	Precipitation gauge 1	mm	A
PRECIP2	precip2	Precipitation gauge 2	mm	A
SRAVG	srad	Solar radiation avg	W m⁻²	A
WSPD2MAVG	wspd_2m_avg	Wind speed 2 m avg	m s⁻¹	A
WSPD2MMAX	wspd_2m_max	Wind speed 2 m max	m s⁻¹	H¹
WDIR2M	wdir_2m	Wind direction 2 m	°	A
WDIR2MSTD	wdir_2m_std	Wind direction 2 m std dev	°	A
WSPD10MAVG	wspd_10m_avg	Wind speed 10 m avg	m s⁻¹	A
WSPD10MMAX	wspd_10m_max	Wind speed 10 m max	m s⁻¹	H¹
WDIR10M	wdir_10m	Wind direction 10 m	°	A
WDIR10MSTD	wdir_10m_std	Wind direction 10 m std dev	°	A

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

Soil temperature — dedicated probes

API name	snake_case	Description	Unit	Intervals
SOILTMP5AVG	tsoil_5cm	Soil temperature 5 cm avg	°C	A
SOILTMP5MIN	tsoil_5cm_min	Soil temperature 5 cm min	°C	D
SOILTMP5MAX	tsoil_5cm_max	Soil temperature 5 cm max	°C	D
SOILTMP10AVG	tsoil_10cm	Soil temperature 10 cm avg	°C	A
SOILTMP10MIN	tsoil_10cm_min	Soil temperature 10 cm min	°C	D
SOILTMP10MAX	tsoil_10cm_max	Soil temperature 10 cm max	°C	D

Soil — CS655 sensors

API name	snake_case	Description	Unit	Intervals
SOILTMP5AVG655	tsoil_5cm_655	Soil temperature 5 cm	°C	A
SOILTMP10AVG655	tsoil_10cm_655	Soil temperature 10 cm	°C	A
SOILTMP20AVG655	tsoil_20cm_655	Soil temperature 20 cm	°C	A
SOILTMP50AVG655	tsoil_50cm_655	Soil temperature 50 cm	°C	A
SOILKA5CM	ka_5cm	Dielectric constant 5 cm	—	A
SOILKA10CM	ka_10cm	Dielectric constant 10 cm	—	A
SOILKA20CM	ka_20cm	Dielectric constant 20 cm	—	A
SOILKA50CM	ka_50cm	Dielectric constant 50 cm	—	A
SOILEC5CM	ec_5cm	Electrical conductivity 5 cm	dS m⁻¹	A
SOILEC10CM	ec_10cm	Electrical conductivity 10 cm	dS m⁻¹	A
SOILEC20CM	ec_20cm	Electrical conductivity 20 cm	dS m⁻¹	A
SOILEC50CM	ec_50cm	Electrical conductivity 50 cm	dS m⁻¹	A
VWC5CM	vwc_5cm	Volumetric water content 5 cm	m³ m⁻³	A
VWC10CM	vwc_10cm	Volumetric water content 10 cm	m³ m⁻³	A
VWC20CM	vwc_20cm	Volumetric water content 20 cm	m³ m⁻³	A
VWC50CM	vwc_50cm	Volumetric water content 50 cm	m³ m⁻³	A

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.

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