Utility Functions for Production R Code

A suite of utility functions providing functionality commonly needed for production level projects such as logging, error handling, cache management and date-time parsing. Functions for date-time parsing and formatting require that time zones be specified explicitly, avoiding a common source of error when working with environmental time series.

MazamaCoreUtils

MazamaCoreUtils is a suite of utility functions for production-level R code, providing functionality commonly needed by operational systems such as logging, error handling, cache management and date-time parsing.

Functions for date-time parsing and formatting require that timezones be specified explicitly, avoiding a common source of error when working with environmental time series.

Installation

Install the released version from CRAN:

install.packages("MazamaCoreUtils")

Install the development version from GitHub:

remotes::install_github("MazamaScience/MazamaCoreUtils")

MazamaCoreUtils requires R version 4.0.0 or later.

Example

Set up standard log files, request a range of days in an explicit timezone and record the request in the log:

library(MazamaCoreUtils)

# Create TRACE, DEBUG, INFO, WARN and ERROR log files
logDir <- file.path(tempdir(), "logs")
initializeLogging(logDir)

# Date-times always require an explicit timezone
tlim <- dateRange("2024-03-01", "2024-03-03", timezone = "America/Los_Angeles")
tlim
#> [1] "2024-03-01 00:00:00 PST" "2024-03-02 23:59:59 PST"

logger.info(
  "Requesting data from %s to %s",
  timeStamp(tlim[1], timezone = "America/Los_Angeles", unit = "min", style = "human"),
  timeStamp(tlim[2], timezone = "America/Los_Angeles", unit = "min", style = "human")
)

readLines(file.path(logDir, "INFO.log"))

Overview

Logging — initializeLogging(), logger.setup(), logger.setLevel(), logger.info(), logger.error()
Error handling and NULL values — stopOnError(), stopIfNull(), setIfNull()
Date-times with explicit timezones — parseDatetime(), dateRange(), timeRange(), dateSequence(), timeStamp()
Locations — validateLonLat(), createLocationMask(), createLocationID()
Cache management and data loading — manageCache(), loadDataFile()
API keys — setAPIKey(), getAPIKey(), showAPIKeys()
HTML utilities — html_getLinks(), html_getTables()
Code linting and package checks — lintFunctionArgs_file(), timezoneLintRules, check_fast()

Detailed argument and return value documentation is available in the function help pages, for example ?parseDatetime.

Background

MazamaCoreUtils was created by Mazama Science to standardize the work of building R packages, data processing pipelines and web services focused on environmental monitoring data. Its functions are used by other Mazama Science packages and by systems that are run operationally, where consistent logging, clear error messages and unambiguous timezones matter.

Documentation and Help

CRAN package page for the reference manual and vignettes on cache management, date parsing, error handling and logging
GitHub Issues for bug reports
GitHub Discussions for announcements, support and building a community of practice around this package

Questions regarding further development of the package can also be directed to [email protected].