preMetabolizer

preMetabolizer helps turn field and public environmental data into the regular, physically consistent inputs needed for stream metabolism models. It is designed for the work that usually happens before streamMetabolizer: finding nearby weather stations, downloading meteorological and elevation data, standardizing timestamps, converting units, and calculating light, pressure, dissolved gas, and water property variables.

The package is most useful when you need to:

Installation

preMetabolizer is not on CRAN. Install the development version from GitHub:

# install.packages("pak")
# pak::pak("ConnorB/preMetabolizer")
install.packages("preMetabolizer", repos = c('https://connorb.r-universe.dev', 'https://cloud.r-project.org'))

Or with remotes:

# install.packages("remotes")
# remotes::install_github("ConnorB/preMetabolizer")
install.packages("preMetabolizer", repos = c('https://connorb.r-universe.dev', 'https://cloud.r-project.org'))

The package requires R (>= 4.1.0). streamMetabolizer is no longer a hard dependency; install it separately if you intend to fit metabolism models on the prepared data.

Quick start

Most workflows begin with logger data that contain a timestamp, observed dissolved oxygen, and water temperature. The example below uses the built-in French Creek dataset and builds the core columns expected by streamMetabolizer::metab().

library(preMetabolizer)
library(dplyr)

data(french_creek)

site_latitude <- 41.329678
site_longitude <- -106.359058
site_elev_m <- 3115

metab_input <- french_creek |>
  filter(
    sonde == "TOWN",
    is.na(temp_C) | temp_C >= 0,
    is.na(DO_mgL) | DO_mgL > 5
  ) |>
  select(datetime, DO_mgL, temp_C) |>
  even_timesteps(datetime_col = "datetime") |>
  mutate(
    solar.time = convert_to_solar_time(
      datetime,
      longitude = site_longitude
    ),
    light = calc_par(
      solar.time,
      latitude = site_latitude,
      longitude = site_longitude
    ),
    bp_kPa = correct_bp(
      station_bp = 101.325,
      air_temp = temp_C,
      station_elev = 0,
      site_elev = site_elev_m
    ),
    DO.sat = calc_o2_sat(temp_C, bp_kPa, units = "kPa")
  ) |>
  transmute(
    solar.time,
    DO.obs = DO_mgL,
    DO.sat,
    depth = 0.16,
    temp.water = temp_C,
    light
  )

head(metab_input)

For a more complete version of this workflow, including observed light from NASA POWER, see vignette("french-creek", package = "preMetabolizer").

Network-backed vignettes are skipped during package checks by default. Set PREMETABOLIZER_RUN_VIGNETTES=true when you want to refresh them interactively.

Common tasks

Physical and chemical calculations

library(preMetabolizer)

# Dissolved oxygen saturation at 15°C, standard atmosphere, freshwater
calc_o2_sat(temp_water = 15, atmo_press = 1, units = "atm")
#> [1] 10.08393

# Water density (kg/m³) at several temperatures
calc_water_density(water_temp = c(0, 10, 20, 30))
#> [1] 999.8428 999.7027 998.2067 995.6488

# Barometric pressure correction from a station at 300 m to a site at 500 m
correct_bp(station_bp = 101.3, air_temp = 15, station_elev = 300, site_elev = 500)
#> [1] 98.92626

# Dissolved CO2 concentration from xCO2, pressure, and water depth
calc_co2_mg_l(
  co2_ppm = 420,
  temp_water = 20,
  water_depth_m = 0.5,
  atmo_press = 101.325,
  press_units = "kPa"
)

Unit conversion

# Stream discharge: cfs → cms
convert_flow(14.32, from = "cfs", to = "cms")
#> [1] 0.4054972

# Barometric pressure: kPa → atm
convert_pressure(101.325, from = "kPa", to = "atm")
#> [1] 1

Solar radiation and light

# Convert a UTC timestamp to mean solar time at a site in Kansas
utc <- as.POSIXct("2024-06-21 18:00:00", tz = "UTC")
solar <- convert_to_solar_time(utc, longitude = -96.6)

# Model PAR near local solar noon on the summer solstice
noon_solar <- convert_to_solar_time(
  as.POSIXct("2024-06-21 18:00:00", tz = "UTC"),
  longitude = -96.6
)
calc_par(noon_solar, latitude = 39.1, longitude = -96.6)

Time series utilities

# Flag outliers with a moving-window robust Z-score
x <- c(1.0, 1.2, 1.1, 1.3, 50.0, 1.1, 1.2, 1.0)
flag_z(x, width = 5, threshold = 3)
#> [1] NA  NA  NA  NA  "Z" NA  NA  NA

# Determine meteorological season from a date
get_season(c("2024-01-15", "2024-04-15", "2024-07-04", "2024-10-15"))
#> [1] "Winter" "Spring" "Summer" "Autumn"

Public data access

Network functions download or query public data services and are best run interactively. Results are cached where possible.

# Find NOAA stations near a site
closest_noaa_stations(
  latitude = 39.1068806,
  longitude = -96.6117151,
  dist_km = 50
)

# Add NASA POWER pressure, radiation, precipitation, and air temperature
site_data <- data.frame(
  dateTime = as.POSIXct("2024-06-01 12:00:00", tz = "UTC")
)

get_nasa_data(
  site_data,
  latitude = 39.1,
  longitude = -96.6,
  elev_m = 320
)

Learn more

License

AGPL (>= 3). See LICENSE.md.

Issues

Bug reports and feature requests are welcome at https://github.com/ConnorB/preMetabolizer/issues.