Merge pull request #17 from NewGraphEnvironment/1-metadata-utilities

Add metadata and utility functions (#1, #2, #3)

Author: NewGraphEnvironment

NAMESPACE

@@ -1,2 +1,7 @@
 # Generated by roxygen2: do not edit by hand
 
+export(cd_cache_clear)
+export(cd_cache_info)
+export(cd_cache_path)
+export(cd_periods)
+export(cd_variables)

R/cd_cache.R

@@ -0,0 +1,67 @@
+#' Get cd cache directory path
+#'
+#' Returns the path to the cd cache directory. Creates it if
+#' it doesn't exist.
+#'
+#' @param cache_dir Character. Override the default cache location.
+#'   If NULL, uses `rappdirs::user_cache_dir("cd")`.
+#'
+#' @return Character path to the cache directory.
+#'
+#' @examples
+#' cd_cache_path()
+#'
+#' @export
+cd_cache_path <- function(cache_dir = NULL) {
+  path <- cache_dir %||% rappdirs::user_cache_dir("cd")
+  if (!dir.exists(path)) {
+    dir.create(path, recursive = TRUE, showWarnings = FALSE)
+  }
+  path
+}
+
+#' Clear the cd cache
+#'
+#' Removes all cached files from the cd cache directory.
+#'
+#' @param cache_dir Character. Override the default cache location.
+#'
+#' @return Invisibly returns the number of files removed.
+#'
+#' @examples
+#' \dontrun{
+#' cd_cache_clear()
+#' }
+#'
+#' @export
+cd_cache_clear <- function(cache_dir = NULL) {
+  path <- cd_cache_path(cache_dir)
+  if (!dir.exists(path)) return(invisible(0L))
+  files <- list.files(path, recursive = TRUE, full.names = TRUE)
+  n <- length(files)
+  if (n > 0) unlink(path, recursive = TRUE)
+  invisible(n)
+}
+
+#' Show cd cache info
+#'
+#' Reports the cache location and size.
+#'
+#' @param cache_dir Character. Override the default cache location.
+#'
+#' @return A list with `path`, `n_files`, and `size_mb`.
+#'
+#' @examples
+#' cd_cache_info()
+#'
+#' @export
+cd_cache_info <- function(cache_dir = NULL) {
+  path <- cd_cache_path(cache_dir)
+  files <- list.files(path, recursive = TRUE, full.names = TRUE)
+  size <- if (length(files) > 0) sum(file.size(files), na.rm = TRUE) else 0
+  list(
+    path = path,
+    n_files = length(files),
+    size_mb = round(size / 1024^2, 2)
+  )
+}

R/cd_periods.R

@@ -0,0 +1,23 @@
+#' Valid temporal aggregation periods
+#'
+#' Returns the set of temporal periods supported by the cd package.
+#' Used for input validation and iteration in extraction and analysis
+#' functions.
+#'
+#' @param include_monthly Logical. If `TRUE`, appends the 12 calendar
+#'   months (Jan, Feb, ..., Dec) to the seasonal periods. Default `FALSE`.
+#'
+#' @return Character vector of period names.
+#'
+#' @examples
+#' cd_periods()
+#' cd_periods(include_monthly = TRUE)
+#'
+#' @export
+cd_periods <- function(include_monthly = FALSE) {
+  periods <- c("annual", "winter", "spring", "summer", "fall")
+  if (include_monthly) {
+    periods <- c(periods, month.abb)
+  }
+  periods
+}

R/cd_variables.R

@@ -0,0 +1,45 @@
+#' Climate variable metadata
+#'
+#' Returns a tibble of metadata for the seven climate variables supported
+#' by the cd package. Used internally for unit labels, anomaly type routing,
+#' and ERA5-Land API variable names.
+#'
+#' @return A tibble with columns:
+#'   \describe{
+#'     \item{variable}{Short name used throughout the package.}
+#'     \item{long_name}{Human-readable label for plots and tables.}
+#'     \item{unit}{Measurement unit (degree C, percent, Pa).}
+#'     \item{anomaly_type}{"absolute" for direct departures, "pct_normal"
+#'       for percent-of-normal anomalies.}
+#'     \item{era5_name}{ERA5-Land variable name for CDS API requests,
+#'       or NA for derived variables.}
+#'   }
+#'
+#' @examples
+#' cd_variables()
+#' cd_variables()$variable
+#'
+#' @export
+cd_variables <- function() {
+  tibble::tibble(
+    variable = c("tmean", "tmax", "tmin", "prcp", "vpd", "rh", "soil_moisture"),
+    long_name = c(
+      "Mean temperature", "Maximum temperature", "Minimum temperature",
+      "Precipitation", "Vapour pressure deficit", "Relative humidity",
+      "Soil moisture"
+    ),
+    unit = c("\u00b0C", "\u00b0C", "\u00b0C", "%", "Pa", "%", "%"),
+    anomaly_type = c(
+      "absolute", "absolute", "absolute",
+      "pct_normal",
+      "absolute", "absolute",
+      "pct_normal"
+    ),
+    era5_name = c(
+      "2m_temperature", NA_character_, NA_character_,
+      "total_precipitation",
+      NA_character_, NA_character_,
+      NA_character_
+    )
+  )
+}

man/cd_cache_clear.Rd

@@ -0,0 +1,26 @@
+# Progress
+
+## Status: Complete
+
+### cd_variables() — Issue #1
+- [x] Implementation
+- [x] Tests
+- [x] Docs
+- [x] Committed
+
+### cd_periods() — Issue #2
+- [x] Implementation
+- [x] Tests
+- [x] Docs
+- [x] Committed
+
+### cd_cache_*() — Issue #3
+- [x] Implementation
+- [x] Tests
+- [x] Docs
+- [x] Committed
+
+### Final
+- [x] `devtools::test()` all pass (25/25)
+- [x] `lintr::lint_package()` clean
+- [ ] PR created