R/odf_update_metadata.R

In pkraska/CESD: `CESD`: do common science data management task in the Coastal Ecosystem Science Division (CESD)

#' Update existing ODF format list with standard metadata and project/deployment
#' level metadata
#'
#' @param x R object to update
#' @param project Which program/project collected this data? Required if going
#'   to the ODIS datashop for a cruise number, or just for knowing what program
#'   generated the data.
#' @param project_lead the person responsible for this data at the program
#'   level. this is usually the project/program lead, not a field technician
#'   collecting the data.
#' @param latitude latitude in decimal degrees North(dd.ddddd\deg) where the
#'   instrument was moored.
#' @param longitude longitude in decimal degrees East (-ddd.dddd\deg) where the
#'   instrument was deployed *should be negative in the Western Hemisphere!*
#' @param depth_m depth of the instrument in meters.
#' @param depth_type depth type for the instrument deployment, either `surface`
#'   if moored a certain distance from the surface (e.g. moored to a floating
#'   platform), or `bottom` if moored a set distance from the water column
#'   bottom (e.g. moored to solid wharf).
#' @param organization `DFO-MPO` is the default, but if it needs to be more
#'   specific can modify here.
#' @param intitute numeric institute code for the collecting research
#'   institution, BIO is 1810. Don't know where these codes come from.
#' @param min_depth numeric, minimum depth of the instrument (positive, meters)
#' @param max_depth numeric, maximum depth of the instrument (positive, meters)
#' @param sampling_interval numeric, what was the sampling interval of the
#'   instrument in seconds (s)
#' @param sounding numeric, what was the water column depth in meters. Usually
#'   from the ship echosounder, but  could be whatever method to determine the
#'   depoth of the water column.
#' @param depth_off_bottom numeric, depth of the instrument off the bottom in
#'   meters (m). This is only filled out when the instrument is moored to a
#'   fixed depth off of the bottom. This is NOT used if the instrument is
#'   surface moored (e.g. 1 m below the surface on a floating dock)
#' @param event_comments character string, additional comments to describe the
#'   event, and conditions surrounding it to better interpret the data.
#'
#' @returns an updated list of metadata for the creation of an ODF compliant
#'   file
#' @export
#'
#' @examples odf_update_metadata(project = "CSRF1234",
#' project_lead = "Joe Somebody",
#' organization = "DFO-MPO",
#' latitude = 45,
#' longitude = -65,
#' depth_m = 10,
#' depth_type = "bottom")

odf_update_metadata <- function(
  x,
  project,
  project_lead,
  organization = c("DFO-MPO", "DFO-MPO MARSCI", "DFO-MPO CESD"),
  institute = NA_integer_,
  latitude,
  longitude,
  end_latitude = NA_real_,
  end_longitude = NA_real_,
  depth_m,
  depth_type = c("surface", "bottom"),
  min_depth,
  max_depth,
  sampling_interval = NA_real_,
  sounding = NA_real_,
  depth_off_bottom = NA_real_,
  event_comments
) {
  x[['cruise_header']][['cruise_name']] <- project
  x[['cruise_header']][['chief_scientist']] <- project_lead
  x[['cruise_header']][['organization']] <- organization
  x[['cruise_header']][['country_institute_code']] <- institute
  x[['event_header']][['initial_latitude']] <- latitude
  x[['event_header']][['initial_longitude']] <- longitude

  if (is.na(end_latitude)) {
    x[['event_header']][['end_latitude']] <- NA_real_
  } else {
    x[['event_header']][['end_latitude']] <- end_latitude
  }

  if (is.na(end_longitude)) {
    x[['event_header']][['end_longitude']] <- NA_real_
  } else {
    x[['event_header']][['end_longitude']] <- end_longitude
  }

  if (depth_type == "surface") {
    message(
      'Remember, this is depth FROM the SURFACE. The minimum and maximum depths correspond to the depth in the water column, so if this was attached to a floating platform, they will likely be the same depth.'
    )
  }

  if (depth_type == "bottom") {
    message(
      'Remember, this is depth FROM the BOTTOM. The minimum and maximum depths correspond to the depth in the water column, so if this was moored to a fixed point, thee depth corresponds to the depth opf the water column above the instrument.'
    )
  }
}