R: Handle Flags in adp Objects

handleFlags,adp-method {oce} | R Documentation

## Handle Flags in adp 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.

### Usage

    ## S4 method for signature 'adp'
    handleFlags(object, flags = NULL, actions = NULL,
      debug = getOption("oceDebug"))

### Arguments

`object` | A `adp` object, i.e. one inheriting from `adp-class`.
`flags` | A `list` specifying flag values upon which actions will be taken. This can take two forms. In the first, the list has named elements each containing a vector of integers. For example, salinities flagged with values of 1 or 3 through 9 would be specified by `flags=list(salinity=c(1,3:9))`. Several data items can be specified, e.g. `flags=list(salinity=c(1,3:9), temperature=c(1,3:9))` indicates that the actions are to take place for both salinity and temperature. In the second form, `flags` is a list with unnamed vectors, and this means to apply the actions to all the data entries; thus, `flags=list(c(1,3:9))` means to apply not just to salinity and temperature, but also to everything else that is in the `data` slot. If `flags` is not provided, then `defaultFlags` is called, to try to determine a conservative default.
`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 consider a flag value of 1 to indicate bad data, and 0 to indicate good data. Note that it only makes sense to use velocity (`v`) flags, because other flags are, at least for some instruments, stored as `raw` quantities, and such quantities may not be set to `NA`.

### See Also

Other functions relating to data-quality flags: `defaultFlags`, `handleFlags,argo-method`, `handleFlags,ctd-method`, `handleFlags,section-method`, `handleFlags`, `initializeFlagScheme,ctd-method`, `initializeFlagScheme,oce-method`, `initializeFlagScheme,section-method`, `initializeFlagScheme`, `initializeFlags,adp-method`, `initializeFlags,oce-method`, `initializeFlags`, `setFlags,adp-method`, `setFlags,ctd-method`, `setFlags,oce-method`, `setFlags`

Other things related to `adp` data: `[[,adp-method`, `[[<-,adp-method`, `adp-class`, `adpEnsembleAverage`, `adp`, `as.adp`, `beamName`, `beamToXyzAdp`, `beamToXyzAdv`, `beamToXyz`, `beamUnspreadAdp`, `binmapAdp`, `enuToOtherAdp`, `enuToOther`, `plot,adp-method`, `read.ad2cp`, `read.adp.nortek`, `read.adp.rdi`, `read.adp.sontek.serial`, `read.adp.sontek`, `read.adp`, `read.aquadoppHR`, `read.aquadoppProfiler`, `read.aquadopp`, `rotateAboutZ`, `setFlags,adp-method`, `subset,adp-method`, `summary,adp-method`, `toEnuAdp`, `toEnu`, `velocityStatistics`, `xyzToEnuAdp`, `xyzToEnu`

### Examples

    # Flag low "goodness" or high "error beam" values.
    library(oce)
    data(adp)
    # Same as Example 2 of ?'setFlags,adp-method'
    v <- adp[["v"]]
    i2 <- array(FALSE, dim=dim(v))
    g <- adp[["g", "numeric"]]
    # Thresholds on percent "goodness" and error "velocity"
    G <- 25
    V4 <- 0.45
    for (k in 1:3)
        i2[,,k] <- ((g[,,k]+g[,,4]) < G) | (v[,,4] > V4)
    adpQC <- initializeFlags(adp, "v", 2)
    adpQC <- setFlags(adpQC, "v", i2, 3)
    adpClean <- handleFlags(adpQC, flags=list(3), actions=list("NA"))
    # Demonstrate (subtle) change graphically.
    par(mfcol=c(2, 1))
    plot(adp, which="u1")
    plot(adpClean, which="u1")

[Package oce version 1.0-1 Index]