oce (version 0.9-23)

handleFlags,ctd-method: Handle Flags in CTD Objects

Description

Data-quality flags are stored in the metadata slot of oce-class objects in a list named flags. The present function (a generic that has specialized versions for various data classes) provides a way to manipulate the core data based on the data-quality flags. For example, a common operation is to replace suspicious or erroneous data with NA.

If metadata$flags in the object supplied as the first argument is empty, then that object is returned, unaltered. Otherwise, handleFlags analyses the data-quality flags within the object, in relation to the flags argument, and interprets the action argument to select an action to be applied to matched data.

Reasonable defaults are used if flags and actions are not supplied (see ‘Details’), but different schemes are used in different data archives, so it is risky to rely on these defaults. It is usually necessary to tailor flags and actions to the data and the analysis goals.

Usage

# S4 method for ctd
handleFlags(object, flags = list(), actions = list(),
  debug = integer())

Arguments

object

A ctd object, i.e. one inheriting from ctd-class.

flags

An optional list containing (a) items with names of entries in the data slot of object, or (b) a single unnamed item. In the first case, the attention is focussed on the named items, while in the second case the all the data in the object's data slot are examined. Each element in the list must be set to an integer or vector of integers, specifying conditions to be met before actions are to be taken. See “Details” for the default that is used if flags is not supplied.

actions

An optional list that contains items with names that match those in the flags argument. If actions is not supplied, the default will be to set all values identified by flags to NA; this can also be specified by specifying actions=list("NA"). It is also possible to specify functions that calculate replacement values. These are provided with object as the single argument, and must return a replacement for the data item in question. See “Details” for the default that is used if actions is not supplied.

debug

An optional integer specifying the degree of debugging, with value 0 meaning to skip debugging and 1 or higher meaning to print some information about the arguments and the data. It is usually a good idea to set this to 1 for initial work with a dataset, to see which flags are being handled for each data item. If not supplied, this defaults to the value of getOption("oceDebug").

Details

If flags and actions are not provided, the default is to use WHP (World Hydrographic Program) flags [1], in which the value 2 indicates good data, and other values indicate either unchecked, suspicious, or bad data. Any data not flagged as good are set to NA in the returned value. (An exception is for salinity: if the item named salinity has a bad flag but salinityBottle has a good flag, then the bottle value is substituted, and a warning is issued.) Since WHP flag codes run from 1 to 9, this default is equivalent to setting flags=list(all=c(1, 3:9)) along with action=list("NA").

References

1. https://www.nodc.noaa.gov/woce/woce_v3/wocedata_1/whp/exchange/exchange_format_desc.htm

See Also

Other functions that handle data-quality flags: handleFlags,argo-method, handleFlags,section-method, handleFlags

Other things related to ctd data: [[,ctd-method, [[<-,ctd-method, as.ctd, cnvName2oceName, ctd-class, ctdDecimate, ctdFindProfiles, ctdRaw, ctdTrim, ctd, oceNames2whpNames, oceUnits2whpUnits, plot,ctd-method, plotProfile, plotScan, plotTS, read.ctd.itp, read.ctd.odf, read.ctd.sbe, read.ctd.woce.other, read.ctd.woce, read.ctd, subset,ctd-method, summary,ctd-method, woceNames2oceNames, woceUnit2oceUnit, write.ctd

Examples

# NOT RUN {
library(oce)
data(section)
stn <- section[["station", 100]]
# 1. Default: anything not flagged as 2 is set to NA, to focus
# solely on 'good', in the World Hydrographic Program scheme.
STN <- handleFlags(stn)
data.frame(old=stn[['salinity']], flag=stn[['salinityFlag']], new=STN[['salinity']])

# 2. A less restrictive case: include also 'questionable' data,
# and only apply this action to salinity.
STN <- handleFlags(stn, flags=list(salinity=c(1, 4:9)))

# 3. A Canadian Department of Fisheries and Oceans convention for
# some of its data files lists flags as 0=unchecked, 1=good,
# 2=uncertain, 3=doubtful, 4=wrong, and 5=changed, so a
# trusting arrangement would be to discard 2:4, and a more
# cautious approach would be to also discard 0.
STN <- handleFlags(stn, flags=list(2:4))
STN <- handleFlags(stn, flags=list(c(0,2:4)))

# 4. Use smoothed TS relationship to nudge questionable data.
# This is not a recommended procedure, but rather just a simple
# illustration of how to supply a function for an action.
f<-function(x) {
  S <- x[["salinity"]]
  T <- x[["temperature"]]
  df <- 0.5 * length(S) # smooths a bit
  sp <- smooth.spline(T, S, df=df)
  0.5 * (S + predict(sp, T)$y)
}
par(mfrow=c(1,2))
STN <- handleFlags(stn, flags=list(salinity=c(1,3:9)), action=list(salinity=f))
plotProfile(stn, "salinity", mar=c(3, 3, 3, 1))
p <- stn[['pressure']]
par(mar=c(3, 3, 3, 1))
plot(STN[['salinity']] - stn[['salinity']], p, ylim=rev(range(p)))

# }