R/pvolfile.R

Defines functions is.odimfile get_odim_object_type is.pvolfile

Documented in get_odim_object_type is.pvolfile

#' Check if a local file is a polar volume (\code{pvol})
#'
#' Check whether a file is a polar volume in ODIM HDF5 format that can be read with
#' package \pkg{bioRad}
#'
#' @param file A string containing a file name.
#' @param filename Deprecated argument, use file instead.
#'
#' @return TRUE when \code{file} is a polar volume in readable format,
#' otherwise FALSE
#'
#' @export
#' @details
#' The function checks whether a HDF5 file provided as input is a polar volume
#' in ODIM HDF5 format. The function currently evaluates to FALSE for NEXRAD and
#' IRIS RAW polar volume files.
#'
#' @examples
#' # locate example file:
#' pvolfile <- system.file("extdata", "volume.h5", package = "bioRad")
#'
#' # check that the file is an ODIM HDF5 polar volume:
#' is.pvolfile(pvolfile) # > TRUE
is.pvolfile <- function(file, filename = NULL) {

  # deprecate function arguments
  if (!missing(filename)) {
    warning("argument filename is deprecated; please use file instead.",
      call. = FALSE
    )
    file <- filename
  }

  type <- get_odim_object_type(file)
  if (is.na(type)) {
    return(FALSE)
  } else {
    return(type == "PVOL")
  }
}

#' Check the data object contained in a ODIM HDF5 file
#'
#' Checks which data object is contained in ODIM HDF5 file
#'
#' @param file A string containing a file name.
#'
#' @return character string \code{PVOL} for polar volume, \code{VP} for
#' vertical profile. 
#'
#' @export
#' 
#' @details
#' See \href{https://github.com/adokter/vol2bird/blob/master/doc/OPERA2014_O4_ODIM_H5-v2.2.pdf}{ODIM specification}
#' Table 2 for a full list of existing ODIM file object types. 
#' 
#' @examples
#' # locate a polar volume file:
#' pvolfile <- system.file("extdata", "volume.h5", package = "bioRad")
#'
#' # check the data type:
#' get_odim_object_type(pvolfile) # > "PVOL"
get_odim_object_type <- function(file) {
  if (!file.exists(file)) {
    warning(paste(file, "does not exist"))
    return(NA)
  }
  if (!is.odimfile(file)) {
    warning(paste(file, "is not a ODIM HDF5 file"))
    return(NA)
  }
  object <- h5readAttributes(file, "what")$object
  return(object)
}

is.odimfile <- function(file) {
  if (!H5Fis_hdf5(file)) {
    warning(paste(file, "is not a HDF5 file"))
    return(FALSE)
  }
  output <- TRUE
  groups <- h5ls(file, recursive = FALSE)$name
  if (!("dataset1" %in% groups)) {
    output <- FALSE
    warning(paste(
      "HDF5 file", file,
      "does not contain a /dataset1 group"
    ))
  }

  if (!("what" %in% groups)) {
    output <- FALSE
    warning(paste(
      "HDF5 file", file,
      "does not contain a /what group"
    ))
  } else {
    object <- h5readAttributes(file, "what")$object

    if (is.null(object)) {
      warning("'object' attribute not found in /what group")
      output <- FALSE
    }
  }

  if (!("how" %in% groups)) {
    # accepting a missing /how group
    warning(paste("HDF5 file", file, "does not contain a /how group"))
  }
  if (!("where" %in% groups)) {
    output <- FALSE
    warning(paste("HDF5 file", file, "does not contain a /where group"))
  }
  return(output)
}

Try the bioRad package in your browser

Any scripts or data that you put into this service are public.

bioRad documentation built on July 1, 2020, 10:18 p.m.