Add new or update existing monitoring location metadata [Experimental]

add_station_metadata_fields() takes a dataframe of monitoring locations and new metadata supplied by the user, and upserts (add new or update existing) station metadata accordingly. The function then returns the input dataframe with an additional column containing the result of each request.

add_station_metadata_fields(master_dataframe)

Arguments

master_dataframe

A dataframe of monitoring locations, associated metadata fields to be upserted and new data that will be used to upsert the metadata. Typically The dataframe must have the following columns:

  • Field - The name of the metadata field to be upserted.

  • FieldType - The data class of the metadata field to be upserted.

  • FieldValue - The new value of the field to be upserted.

  • Ordinal - TODO: Add description.

  • StationId - An index used to identify unique data sources. Monitoring locations may be associated with one or more StationID number.

Value

A dataframe containing the columns or the input dataframe as well as two additional columns:

  • Id - The unique database index for the retrieved metadata record.

  • Result - A list of requests made NOTE: Shows change made in addition to all metadata records for that StationID.

Details

Important events and metadata about calls of add_station_metadata_fields() are documented by the EnviroDataR logger in the log file edr_logs.txt. More information about the EnviroDataR logger can be found in vignette("envirodatar_request_logger").

If values are being updated for existing metadata fields, users may define the corresponding values for Field, FieldType, Ordinal and StationID themselves, but are advised to use the corresponding columns from the return value of 'get_wq_locations_metadata'.

If new metadata are being added, users may define the StationID themselves, but are advised to use the Id column from the return value of 'get_wq_locations_list'.

Examples

# Add new metadata for two monitoring locations
## Create example dataframe of new metadata
new_metadata <- data.frame(
  StationId = c(001, 001, 002),
  Field = c("Geographic Location", "Class", "Geographic Location"),
  FieldType = c("string", "number", "string"),
  FieldValue = c("Spruce Bay", 3, "Pine Bay"),
  Ordinal = c(1, 1, 1)
)

# Add new metadata for an existing monitoring location
upsert_metadata_result <- add_station_metadata_fields(new_metadata)

# Obtain monitoring locations and existing metadata using 'get_wq_locations_list()' and 'get_wq_location_metadata()'
## Obtain Location and StationId
discrete_location_data <- get_wq_locations_list()
location_of_interest <- discrete_location_data$Location[1]
data_source_id <- discrete_location_data$Id[1]

## Obtain columns needed for input dataframe from existing metadata and remove unnecessary columns
discrete_location_metadata <- get_wq_location_metadata(stations = location_of_interest)
new_metadata <- unique(subset(discrete_location_metadata, select = -c(Id)))

## Add new FieldValue for metadata Field, "Geographic Location" at the location of interest
new_metadata$FieldValue[new_metadata$StationId== data_source_id&new_metadata$Field=="Geographic Location"] <- "Hemlock Bay"

upsert_result <- add_station_metadata_fields(new_metadata)