Skip to contents

Working with TexMesonet data

Source: vignettes/tex-mesonet.qmd

Introduction

TexMesonet is a statewide earth observation network managed by the Texas Water Development Board (TWDB). TWDB stations collect near-real-time weather and soil observations, including air temperature, humidity, precipitation, wind, solar radiation, soil temperature, and soil moisture.

preMetabolizer provides three helpers for the public TexMesonet API:

Note: These functions contact the TexMesonet API and require an internet connection. Set PREMETABOLIZER_RUN_VIGNETTES=true to run the API chunks; they are skipped by default during package installation and checks.

Caching downloaded data

Repeated calls to the TexMesonet API download the same data on every run. This vignette saves each result to a local cache directory the first time it is downloaded and reloads from disk on subsequent runs. The cache lives in tools::R_user_dir("preMetabolizer", which = "cache"), a platform-appropriate, user-specific directory that persists across sessions. Each data-fetching chunk below checks for a cached .rds file, downloads and saves on the first run, and reloads from disk on all subsequent runs.

Discover TWDB stations

Use tex_meso_stations() to retrieve station names, IDs, display IDs, coordinates, elevation, activity status, and online dates.

cache_file <- file.path(cache_dir, "tex_meso_stations.rds")
if (!file.exists(cache_file)) {
  stations <- tex_meso_stations()
  saveRDS(stations, cache_file)
} else {
  stations <- readRDS(cache_file)
}

glimpse(stations)

The active and displayed arguments make it easy to focus on stations that are currently operating and shown by TexMesonet.

cache_file <- file.path(cache_dir, "tex_meso_stations_active.rds")
if (!file.exists(cache_file)) {
  active_stations <- tex_meso_stations(active = TRUE, displayed = TRUE)
  saveRDS(active_stations, cache_file)
} else {
  active_stations <- readRDS(cache_file)
}

active_stations |>
  select(station_id, station_name, display_id, county, latitude, longitude) |>
  arrange(county, station_name)

For station time-series requests, keep the integer station_id. This example finds stations in Blanco County and selects one station ID for later use.

blanco_stations <- active_stations |>
  filter(county == "Blanco") |>
  select(station_id, station_name, display_id, latitude, longitude, elevation)

blanco_stations

site_id <- blanco_stations$station_id[1]

Retrieve current observations

tex_meso_current() returns the most recent available observation from each TWDB station. Not every station measures every parameter, so some columns may contain missing values.

cache_file <- file.path(cache_dir, "tex_meso_current.rds")
if (!file.exists(cache_file)) {
  current <- tex_meso_current()
  saveRDS(current, cache_file)
} else {
  current <- readRDS(cache_file)
}

glimpse(current)

The TexMesonet API reports units in a separate object. preMetabolizer stores that object as a data-frame attribute.

attr(current, "units")

For a quick station check, join current observations to station metadata or filter directly by station_id.

current |>
  filter(station_id == site_id) |>
  select(
    station_id,
    station_name,
    recorded_time,
    air_temp,
    humidity,
    precip,
    wind_speed,
    air_pressure
  )

Retrieve recent time series

tex_meso_time_series() retrieves observations for a single station over a look-back window measured in minutes. By default, variable = "all" uses the TexMesonet charting-fields endpoint and returns all fields available for that station.

cache_file <- file.path(cache_dir, "tex_meso_time_series_blanco.rds")
if (!file.exists(cache_file)) {
  recent <- tex_meso_time_series(
    site_id = site_id,
    prior_minutes = 24 * 60
  )
  saveRDS(recent, cache_file)
} else {
  recent <- readRDS(cache_file)
}

glimpse(recent)

The returned date_time column is parsed as UTC.

range(recent$date_time, na.rm = TRUE)
attr(recent$date_time, "tzone")

Retrieve one variable

TexMesonet also provides smaller single-variable endpoints. Use the variable argument when you only need one series.

cache_file <- file.path(cache_dir, "tex_meso_time_series_blanco_temperature.rds")
if (!file.exists(cache_file)) {
  temperature <- tex_meso_time_series(
    site_id = site_id,
    prior_minutes = 24 * 60,
    variable = "temperature"
  )
  saveRDS(temperature, cache_file)
} else {
  temperature <- readRDS(cache_file)
}

temperature |>
  arrange(date_time) |>
  tail()

attr(temperature, "units")

Available single-variable values are "temperature", "humidity", "barometric_pressure", "precip", and "wind_speed".

Example workflow: station weather summary

The charting-fields endpoint is useful when you want to prepare local meteorological covariates for a stream site. The example below summarizes hourly temperature, humidity, precipitation, and wind speed from the recent station data.

hourly_weather <- recent |>
  mutate(hour = lubridate::floor_date(date_time, "hour")) |>
  group_by(hour) |>
  summarise(
    air_temp_C = mean(air_temp, na.rm = TRUE),
    humidity_pct = mean(humidity, na.rm = TRUE),
    precip_mm = sum(precip, na.rm = TRUE),
    wind_speed_m_s = mean(wind_speed, na.rm = TRUE),
    .groups = "drop"
  )

hourly_weather

Plotting the recent series can help identify gaps or station behavior before combining meteorological data with stream logger observations.

ggplot(hourly_weather, aes(hour, air_temp_C)) +
  geom_line(color = "#2c7fb8") +
  geom_point(color = "#2c7fb8", size = 1.5) +
  labs(
    x = NULL,
    y = "Air temperature (°C)",
    title = "Recent TexMesonet air temperature"
  ) +
  theme_bw()

API scope

These functions use the lightweight TexMesonet API endpoints for TWDB stations. For historical custom downloads, longer date ranges, or non-TWDB provider networks shown in the TexMesonet map viewer, use the TexMesonet Custom Downloads page or the source network recommended by TWDB.