Merge pull request #18 from NewGraphEnvironment/9-consumer-extract

Add consumer extract pipeline (#9, #10, #11)

Author: NewGraphEnvironment

NAMESPACE

@@ -3,5 +3,9 @@
 export(cd_cache_clear)
 export(cd_cache_info)
 export(cd_cache_path)
+export(cd_catalog)
+export(cd_catalog_default)
+export(cd_crop)
+export(cd_extract)
 export(cd_periods)
 export(cd_variables)

R/cd_catalog.R

@@ -0,0 +1,55 @@
+#' Load and parse a STAC catalog
+#'
+#' Reads a static STAC catalog JSON file and returns a tidy tibble
+#' of available climate data COGs. This is the entry point for
+#' consumer-side workflows.
+#'
+#' @param catalog Path or URL to a STAC catalog JSON file.
+#'   Defaults to [cd_catalog_default()].
+#'
+#' @return A tibble with columns:
+#'   \describe{
+#'     \item{variable}{Climate variable short name (e.g., "tmean").}
+#'     \item{period}{Temporal aggregation period (e.g., "annual").}
+#'     \item{href}{Resolved path or URL to the COG file.}
+#'   }
+#'
+#' @examples
+#' cd_catalog(
+#'   system.file("extdata", "example_catalog.json", package = "cd")
+#' )
+#'
+#' @export
+cd_catalog <- function(catalog = cd_catalog_default()) {
+  cat_json <- jsonlite::read_json(catalog)
+  base_dir <- dirname(catalog)
+
+  items <- cat_json$items
+  if (is.null(items) || length(items) == 0) {
+    return(tibble::tibble(variable = character(), period = character(), href = character()))
+  }
+
+  tibble::tibble(
+    variable = vapply(items, function(x) x$properties$`cd:variable`, character(1)),
+    period = vapply(items, function(x) x$properties$`cd:period`, character(1)),
+    href = vapply(items, function(x) {
+      h <- x$assets$data$href
+      if (grepl("^(http|s3|/)", h)) h else file.path(base_dir, h)
+    }, character(1))
+  )
+}
+
+#' Default STAC catalog URL
+#'
+#' Returns the default S3-hosted STAC catalog URL for the cd package.
+#' Override with `options(cd.catalog_url = "...")`.
+#'
+#' @return Character URL.
+#'
+#' @examples
+#' cd_catalog_default()
+#'
+#' @export
+cd_catalog_default <- function() {
+  getOption("cd.catalog_url", default = "https://nge-bc-ce.s3.us-west-2.amazonaws.com/cd/catalog.json")
+}

R/cd_crop.R

@@ -0,0 +1,28 @@
+#' Crop and mask a raster to an AOI
+#'
+#' Reads a COG (local or remote) and crops it to a user-supplied area
+#' of interest polygon. Works with local file paths and remote URLs
+#' via GDAL's `/vsicurl/`.
+#'
+#' @param href Character. Path or URL to a COG or raster file.
+#' @param aoi An `sf` or `SpatVector` polygon to crop to.
+#'
+#' @return A [terra::SpatRaster] cropped and masked to the AOI.
+#'
+#' @examples
+#' href <- system.file("extdata", "example_climate.tif", package = "cd")
+#' aoi <- sf::st_read(
+#'   system.file("extdata", "example_aoi.gpkg", package = "cd"),
+#'   quiet = TRUE
+#' )
+#' r <- cd_crop(href, aoi)
+#' r
+#'
+#' @export
+cd_crop <- function(href, aoi) {
+  r <- terra::rast(href)
+  if (inherits(aoi, "sf") || inherits(aoi, "sfc")) {
+    aoi <- terra::vect(aoi)
+  }
+  terra::crop(r, aoi, snap = "out", mask = TRUE)
+}

R/cd_extract.R

@@ -0,0 +1,62 @@
+#' Extract zonal mean time series for an AOI
+#'
+#' For each variable and period in the catalog, crops the COG to the AOI
+#' and computes the spatial mean per year (band). Returns a tidy tibble
+#' of raw climate values suitable for [cd_baseline()], [cd_anomaly()],
+#' or [cd_trend()].
+#'
+#' @param catalog A tibble from [cd_catalog()] with columns
+#'   `variable`, `period`, `href`.
+#' @param aoi An `sf` or `SpatVector` polygon.
+#' @param variables Character vector of variables to extract.
+#'   Defaults to all variables in `catalog`.
+#' @param periods Character vector of periods to extract.
+#'   Defaults to all periods in `catalog`.
+#' @param years Optional integer vector to filter specific years.
+#'
+#' @return A tibble with columns:
+#'   \describe{
+#'     \item{variable}{Climate variable short name.}
+#'     \item{period}{Temporal aggregation period.}
+#'     \item{year}{Year (integer).}
+#'     \item{value}{Spatial mean of the climate value for this AOI.}
+#'   }
+#'
+#' @examples
+#' catalog <- cd_catalog(
+#'   system.file("extdata", "example_catalog.json", package = "cd")
+#' )
+#' aoi <- sf::st_read(
+#'   system.file("extdata", "example_aoi.gpkg", package = "cd"),
+#'   quiet = TRUE
+#' )
+#' cd_extract(catalog, aoi)
+#'
+#' @export
+cd_extract <- function(catalog, aoi,
+                       variables = catalog$variable,
+                       periods = catalog$period,
+                       years = NULL) {
+  rows <- catalog[catalog$variable %in% variables & catalog$period %in% periods, ]
+
+  results <- lapply(seq_len(nrow(rows)), function(i) {
+    r <- cd_crop(rows$href[i], aoi)
+    means <- terra::global(r, fun = "mean", na.rm = TRUE)
+    yr <- as.integer(names(r))
+
+    tibble::tibble(
+      variable = rows$variable[i],
+      period = rows$period[i],
+      year = yr,
+      value = round(means$mean, 4)
+    )
+  })
+
+  out <- dplyr::bind_rows(results)
+
+  if (!is.null(years)) {
+    out <- out[out$year %in% years, ]
+  }
+
+  out
+}

data-raw/example_climate_tmean.R

@@ -0,0 +1,89 @@
+# Create example data for cd package tests and vignettes
+#
+# Crops real ERA5-Land NC data to a small anonymous bbox.
+# Run interactively — requires bc_climate_anomaly repo at ../bc_climate_anomaly/
+#
+# Output:
+#   inst/extdata/example_aoi.gpkg      — simple bbox polygon (no place names)
+#   inst/extdata/example_climate.tif   — tmean annual, 10 years, COG format
+#   inst/extdata/example_catalog.json  — minimal STAC catalog pointing to the COG
+
+library(terra)
+library(sf)
+library(jsonlite)
+
+# -- Source data ---------------------------------------------------------------
+nc_path <- "../bc_climate_anomaly/ano_clm_trn_data/tmean_ano_annual_1950_+_res25.nc"
+stopifnot(file.exists(nc_path))
+
+# -- Create AOI (anonymous bbox) ----------------------------------------------
+# Small area in northern BC — just coordinates, no place names
+bbox <- c(xmin = -126.75, ymin = 54.1, xmax = -125.75, ymax = 54.7)
+aoi <- st_as_sfc(st_bbox(bbox, crs = 4326))
+aoi <- st_sf(geometry = aoi)
+
+sf::st_write(aoi, "inst/extdata/example_aoi.gpkg", delete_dsn = TRUE, quiet = TRUE)
+message("Wrote: inst/extdata/example_aoi.gpkg")
+
+# -- Crop and subset raster ---------------------------------------------------
+r <- rast(nc_path)
+
+# Use first 10 years (bands 1-10) for manageable size
+r_sub <- r[[1:10]]
+
+# Crop to AOI
+r_crop <- crop(r_sub, vect(aoi), snap = "out")
+
+# Set band names to years
+names(r_crop) <- 1951:1960
+
+# Write as COG
+writeRaster(
+  r_crop,
+  "inst/extdata/example_climate.tif",
+  filetype = "COG",
+  overwrite = TRUE,
+  gdal = c("COMPRESS=DEFLATE")
+)
+message("Wrote: inst/extdata/example_climate.tif (",
+        file.size("inst/extdata/example_climate.tif"), " bytes)")
+
+# -- Create minimal STAC catalog ----------------------------------------------
+catalog <- list(
+  type = "Catalog",
+  id = "cd-example",
+  stac_version = "1.0.0",
+  description = "Example climate data for cd package tests",
+  links = list(
+    list(rel = "root", href = "./example_catalog.json", type = "application/json"),
+    list(rel = "item", href = "#tmean-annual", type = "application/json")
+  ),
+  items = list(
+    list(
+      type = "Feature",
+      stac_version = "1.0.0",
+      id = "tmean-annual",
+      geometry = NULL,
+      bbox = as.numeric(bbox),
+      properties = list(
+        `cd:variable` = "tmean",
+        `cd:period` = "annual",
+        datetime = NULL,
+        start_datetime = "1951-01-01T00:00:00Z",
+        end_datetime = "1960-12-31T23:59:59Z"
+      ),
+      links = list(),
+      assets = list(
+        data = list(
+          href = "./example_climate.tif",
+          type = "image/tiff; application=geotiff; profile=cloud-optimized",
+          title = "Mean temperature annual values"
+        )
+      )
+    )
+  )
+)
+
+write_json(catalog, "inst/extdata/example_catalog.json", pretty = TRUE, auto_unbox = TRUE)
+message("Wrote: inst/extdata/example_catalog.json")
+message("Done.")

inst/extdata/example_aoi.gpkg

@@ -0,0 +1,42 @@
+{
+  "type": "Catalog",
+  "id": "cd-example",
+  "stac_version": "1.0.0",
+  "description": "Example climate data for cd package tests",
+  "links": [
+    {
+      "rel": "root",
+      "href": "./example_catalog.json",
+      "type": "application/json"
+    },
+    {
+      "rel": "item",
+      "href": "#tmean-annual",
+      "type": "application/json"
+    }
+  ],
+  "items": [
+    {
+      "type": "Feature",
+      "stac_version": "1.0.0",
+      "id": "tmean-annual",
+      "geometry": {},
+      "bbox": [-126.75, 54.1, -125.75, 54.7],
+      "properties": {
+        "cd:variable": "tmean",
+        "cd:period": "annual",
+        "datetime": {},
+        "start_datetime": "1951-01-01T00:00:00Z",
+        "end_datetime": "1960-12-31T23:59:59Z"
+      },
+      "links": [],
+      "assets": {
+        "data": {
+          "href": "./example_climate.tif",
+          "type": "image/tiff; application=geotiff; profile=cloud-optimized",
+          "title": "Mean temperature annual values"
+        }
+      }
+    }
+  ]
+}