R/AOImethod.R

In ncdfCF: Easy Access to NetCDF Files with CF Metadata Conventions

#' Area of Interest
#'
#' @description This function constructs the area of interest of an analysis. It
#'   consists of an extent and a resolution of longitude and latitude, all in
#'   decimal degrees.
#'
#'   The AOI is used to define the subset of data to be extracted from a data
#'   variable that has an auxiliary longitude-latitude grid (see the
#'   [CFAuxiliaryLongLat] class) at a specified resolution. The data variable
#'   thus has a primary coordinate system where the horizontal components are
#'   not a geographic system of longitude and latitude coordinates.
#'
#' @details Following the CF Metadata Conventions, axis coordinates represent
#'   the center of grid cells. So when specifying `aoi(20, 30, -10, 10, 1, 2)`,
#'   the south-west grid cell coordinate is at `(20.5, -9)`. If the axes of the
#'   longitude-latitude grid have bounds, then the bounds will coincide with the
#'   AOI and the `CFVariable$subset()` method that uses the AOI will attach
#'   those bounds as attributes to the resulting array.
#'
#'   If no resolution is specified, it will be determined from the separation
#'   between adjacent grid cells in both longitude and latitude directions in
#'   the middle of the area of interest. If no extent is specified (meaning,
#'   none of the values; if some but not all values are specified an error will
#'   be thrown), then the whole extent of the variable is used, extended
#'   outwards by the bounds if they are set or half the resolution otherwise.
#'   Thus, to get the entire extent of the variable but in a longitude-latitude
#'   grid and with a resolution comparable to the resolution at the original
#'   Cartesian coordinate system of the variable, simply pass `aoi()` as an
#'   argument to [CFVariable$subset()][CFVariable]. Note that any missing
#'   arguments are calculated internally and stored in the returned object, but
#'   only after the call to `CFVariable$subset()`.
#'
#'   ## Caching
#'
#'   In data collections that are composed of multiple data variables in a
#'   single netCDF resource, a single auxiliary longitude-latitude grid may be
#'   referenced by multiple data variables, such as in
#'   [ROMS](https://www.myroms.org) data which may have dozens of data variables
#'   using a shared grid. When subsetting with an AOI, the instance of this
#'   class is cached to improve performance. The successive calls to
#'   `CFVariable$subset()` should use the same object returned from a single
#'   call to this function for this caching to work properly.
#'
#' @param lonMin,lonMax,latMin,latMax The minimum and maximum values of the
#'   longitude and latitude of the AOI, in decimal degrees. The longitude values
#'   must agree with the range of the longitude in the data variable to which
#'   this AOI will be applied, e.g. `[-180,180]` or `[0,360]`.
#' @param resX,resY The separation between adjacent grid cell, in the longitude
#'   and latitude directions respectively, in decimal degrees. The permitted
#'   values lie within the range `[0.01 ... 10]`. If `resY` is missing it will
#'   use the value of `resX`, yielding square grid cells.
#'
#' @return The return value of the function is an `R6` object which uses
#'   reference semantics. Making changes to the returned object will be visible
#'   in all copies made of the object.
#'
#' @export
#' @examples
#' (aoi <- aoi(20, 60, -40, -20, 0.5))
aoi <- function(lonMin, lonMax, latMin, latMax, resX, resY) {
  if (missing(resX)) resolution <- c(NULL, NULL)
  else {
    if (missing(resY)) resY <- resX
    resolution <- c(resX, resY)
    .aoi_check_resolution(resolution)
  }

  if (missing(lonMin) && missing(lonMin) && missing(lonMin) && missing(lonMin))
    AOI$new(NULL, NULL, NULL, NULL, resolution)
  else {
    .aoi_check_longitude(lonMin, lonMax)
    .aoi_check_latitude(latMin, latMax)
    AOI$new(lonMin, lonMax, latMin, latMax, resolution)
  }
}

#' The dimensions of the grid of an AOI
#'
#' This method returns the dimensions of the grid that would be created for the
#' AOI.
#'
#' @param x An instance of the `AOI` class.
#'
#' @return A vector of two values giving the longitude and latitude dimensions
#' of the grid that would be created for the AOI.
#' @export
#'
#' @examples
#' a <- aoi(30, 40, 10, 30, 0.1)
#' dim(a)
dim.AOI <- function(x) {
  x$dim
}

# Internal functions -----------------------------------------------------------

.aoi_check_resolution <- function(res) {
  if (res[1L] < 0.01 || res[1L] > 10 || res[2L] < 0.01 || res[2L] > 10)
    stop("Argument 'resolution' is outside of the permitted range of [0.01 ... 10]", call. = FALSE)
}

.aoi_check_longitude <- function(min, max) {
  if (is.null(min) && is.null(max)) return()
  if (is.null(min) && (max > -180 && max <= 360)) return()
  if (is.null(max) && (min >= -180 && min < 360)) return()
  if (min < -180 || (min < 0 && max > 180) || max > 360 || min >= max)
    stop("Longitude range is not valid", call. = FALSE)
}

.aoi_check_latitude <- function(min, max) {
  if (is.null(min) && is.null(max)) return()
  if (is.null(min) && (max > -90 && max <= 90)) return()
  if (is.null(max) && (min >= -90 && min < 90)) return()
  if (min < -90 || max > 90 || min >= max)
    stop("Latitude range is not valid", call. = FALSE)
}