R: Infer variable name, units and scale from a Seabird (.cnv)...

cnvName2oceName {oce} | R Documentation

## Infer variable name, units and scale from a Seabird (.cnv) header line

### Description

This function is used by `read.ctd.sbe()` to infer data names and units from the coding used by Teledyne/Seabird (SBE) `.cnv` files. Lacking access to documentation on the SBE format, the present function is based on inspection of a suite of CNV files available to the `oce` developers.

### Usage

    cnvName2oceName(h, columns = NULL, debug = getOption("oceDebug"))

### Arguments

`h` | The header line.
`columns` | Optional list containing name correspondances, as described for `read.ctd.sbe()`.
`debug` | an integer specifying whether debugging information is to be printed during the processing. This is a general parameter that is used by many `oce` functions. Generally, setting `debug=0` turns off the printing, while higher values suggest that more information be printed. If one function calls another, it usually reduces the value of `debug` first, so that a user can often obtain deeper debugging by specifying higher `debug` values.

### Details

A few sample header lines that have been encountered are:

    # name 4 = t068: temperature, IPTS-68 [deg C]
    # name 3 = t090C: Temperature [ITS-90, deg C]
    # name 4 = t190C: Temperature, 2 [ITS-90, deg C]

Examination of several CNV files suggests that it is best to try to infer the name from the characters between the "`=`" and "`:`" characters, because the material after the colon seems to vary more between sample files.

The table given below indicates the translation patterns used. These are taken from reference 1. The `.cnv` convention for multiple sensors is to include optional extra digits in the name, and these are indicated with `~` in the table; their decoding is done with `grep()`.

It is important to note that this table is by no means complete, since there are a great many SBE names listed in their document (reference 1), plus names not listed there but present in data files supplied by prominent archiving agencies. If an SBE name is not recognized, then the oce name is set to that SBE name. This can cause problems in some other processing steps (e.g. if `swRho()` or a similar function is called with an `oce` object as first argument), and so users are well-advised to rename the items as appropriate. The first step in doing this is to pass the object to `summary()`, to discover the SBE names in question. Then consult the SBE documentation to find an appropriate name for the data, and either manipulate the names in the object data slot directly or use `renameData()` to rename the elements. Finally, please publish an 'issue' on the oce Github site https://github.com/dankelley/oce/issues so that the developers can add the data type in question. (To save development time, there is no plan to add all possible data types without a reasonable and specific expression user interest. Oxygen alone has over forty variants.)

Key | Result | Unit;scale | Notes
`alt` | `altimeter` | m |
`altM` | `altimeter` | m |
`accM` | `acceleration` | m/s^2 |
`bat~` | `beamAttenuation` | 1/m |
`C2-C1S/m` | `conductivityDifference` | S/m |
`C2-C1mS/cm` | `conductivityDifference` | mS/cm |
`C2-C1uS/cm` | `conductivityDifference` | uS/cm |
`c~mS/cm` | `conductivity` | mS/cm |
`cond~mS/cm` | `conductivity` | mS/cm |
`c~S/m` | `conductivity` | S/m |
`cond~S/m` | `conductivity` | S/m |
`c~uS/cm` | `conductivity` | uS/cm |
`cond~uS/cm` | `conductivity` | uS/cm |
`CStarAt~` | `beamAttenuation` | 1/m |
`CStarTr~` | `beamTransmission` | percent |
`density~~` | `density` | kg/m^3 |
`depS` | `depth` | m |
`depSM` | `depth` | m |
`depF` | `depth` | m |
`depFM` | `depth` | m |
`dz/dtM` | `descentRate` | m/s |
`f~` | `frequency` | Hz |
`f~~` | `frequency` | Hz |
`flC~` | `fluorescence` | ug/l; Chelsea Aqua 3 |
`flCM` | `fluorescence` | ug/l; Chelsea Mini Chl Con |
`flCUVA~` | `fluorescence` | ug/l; Chelsea UV Aquatracka |
`flEC-AFL~` | `fluorescence` | mg/m^3; WET Labs ECO-AFL/FLtab
`flS` | `fluorescence` | -; Seatech |
`flScufa~` | `fluorescence` | -; Turner SCUFA (RFU) |
`flSP` | `fluorescence` | -; Seapoint |
`flSPR` | `fluorescence` | -; Seapoint, Rhodamine |
`flSPuv` | `fluorescence` | -; Seapoint, UV |
`flT` | `fluorescence` | -; Turner 10-005 flT |
`gpa` | `geopotentialAnomaly` | -; J/kg |
`latitude` | `latitude` | degN |
`longitude` | `longitude` | degE |
`n2satML/L` | `nitrogenSaturation` | ml/l |
`n2satMg/L` | `nitrogenSaturation` | mg/l |
`n2satumol/kg` | `nitrogenSaturation` | umol/kg |
`nbin` | `nbin` |  |
`obsscufa~` | `backscatter` | NTU; Turner SCUFA |
`opoxMg/L` | `oxygen` | mg/l; Optode, Aanderaa |
`opoxML/L` | `oxygen` | ml/l; Optode, Aanderaa |
`opoxMm/L` | `oxygen` | umol/l; Optode, Aanderaa |
`opoxPS` | `oxygen` | percent; Optode, Aanderaa |
`oxsatML/L` | `oxygen` | ml/l; Weiss |
`oxsatMg/L` | `oxygen` | mg/l; Weiss |
`oxsatMm/Kg` | `oxygen` | umol/kg; Weiss |
`oxsolML/L` | `oxygen` | ml/l; Garcia-Gordon |
`oxsolMg/L` | `oxygen` | mg/l; Garcia-Gordon |
`oxsolMm/Kg` | `oxygen` | umol/kg; Garcia-Gordon |
`par~` | `PAR` | -; Biospherical/Licor |
`par/log` | `PAR` | log; Satlantic |
`ph` | `pH` | - |
`potemp~68C` | `thetaM` | degC; IPTS-68 |
`potemp~90C` | `thetaM` | degC; ITS-90 |
`pr` | `pressure` | dbar | 1
`prM` | `pressure` | dbar |
`pr50M` | `pressure` | dbar; SBE50 |
`prSM` | `pressure` | dbar |
`prDM` | `pressure` | dbar; digiquartz |
`prdE` | `pressure` | psi; strain gauge | 2
`prDE` | `pressure` | psi; digiquartz | 2
`prdM` | `pressure` | dbar; strain gauge |
`prSM` | `pressure` | dbar; strain gauge |
`ptempC` | `pressureTemperature` | degC; ITS-90 | 3
`pumps` | `pumpStatus` |  |
`rhodflTC~` | `Rhodamine` | ppb; Turner Cyclops |
`sal~~` | `salinity` | -, PSS-78 | 4
`sbeox~ML/L` | `oxygen` | ml/l; SBE43 |
`sbox~ML/L` | `oxygen` | ml/l; SBE43 (?) |
`sbeox~Mm/Kg` | `oxygen` | umol/kg; SBE43 |
`sbox~Mm/Kg` | `oxygen` | umol/kg; SBE43 (?) |
`sbeox~Mm/L` | `oxygen` | umol/l; SBE43 |
`sbox~Mm/L` | `oxygen` | umol/l; SBE43 (?) |
`sbeox~PS` | `oxygen` | percent; SBE43 |
`sbox~PS` | `oxygen` | percent; SBE43 (?) |
`sbeox~V` | `oxygenRaw` | V; SBE43 |
`sbox~V` | `oxygenRaw` | V; SBE43 (?) |
`scan` | `scan` | - |
`seaTurbMtr~` | `turbidity` | FTU; Seapoint |
`secS-priS` | `salinityDifference` | -, PSS-78 |
`sigma-t` | `sigmaT` | kg/m^3 |
`sigma-theta` | `sigmaTheta` | kg/m^3 | 5
`sigma-`é | `sigmaTheta` | kg/m^3 | 5
`spar` | `spar` | - |
`specc` | `conductivity` | uS/cm |
`sva` | `specificVolumeAnomaly` | 1e-8 m^3/kg; |
`svCM~` | `soundSpeed` | m/s; Chen-Millero |
`T2~68C` | `temperatureDifference` | degC; IPTS-68 |
`T2~90C` | `temperatureDifference` | degC; ITS-90 |
`t~68` | `temperature` | degC; IPTS-68 |
`t~90` | `temperature` | degC; ITS-90 |
`t~68` | `temperature` | degC; IPTS-68 |
`t~68C` | `temperature` | degC; IPTS-68 |
`t~90C` | `temperature` | degC; ITS-90 |
`t090Cm` | `temperature` | degC; ITS-90 |
`t4990C` | `temperature` | degC; ITS-90 |
`tnc90C` | `temperature` | degC; ITS-90 |
`tsa` | `thermostericAnomaly` | 1e-8 m^3/kg |
`tv290C` | `temperature` | degC; ITS-90 |
`t4968C` | `temperature` | degC; IPTS-68 |
`tnc68C` | `temperature` | degC; IPTS-68 |
`tv268C` | `temperature` | degC; IPTS-68 |
`t190C` | `temperature` | degC; ITS-90 |
`tnc290C` | `temperature` | degC; ITS-90 |
`tnc268C` | `temperature` | degC; IPTS-68 |
`t3890C~` | `temperature` | degC; ITS-90 |
`t38~90C` | `temperature` | degC; ITS-90 |
`t3868C~` | `temperature` | degC; IPTS-68 |
`t38~38C` | `temperature` | degC; IPTS-68 |
`timeH` | `timeH` | hour; elapsed |
`timeJ` | `timeJ` | julian day |
`timeJV2` | `timeJV2` | julian day |
`timeK` | `timeK` | s; since Jan 1, 2000 |
`timeM` | `timeM` | minute; elapsed |
`timeN` | `timeN` | s; NMEA since Jan 1, 1970 |
`timeQ` | `timeQ` | s; NMEA since Jan 1, 2000 |
`timeS` | `timeS` | s; elapsed |
`turbflTC~` | `turbidity` | NTU; Turner Cyclops |
`turbflTCdiff` | `turbidityDifference` | NTU; Turner Cyclops |
`turbWETbb~` | `turbidity` | 1/(m\*sr); WET Labs ECO |
`turbWETbbdiff` | `turbidityDifference` | 1/(m\*sr); WET Labs ECO |
`turbWETntu~` | `turbidity` | NTU; WET Labs ECO |
`turbWETntudiff` | `turbidityDifference` | NTU; WET Labs ECO |
`upoly~` | `upoly` | - |
`user~` | `user` | - |
`v~~` | `voltage` | V |
`wetBAttn` | `beamAttenuation` | 1/m; WET Labs AC3 |
`wetBTrans` | `beamTransmission` | percent; WET Labs AC3 |
`wetCDOM~` | `fluorescence` | mg/m^3; WET Labs CDOM |
`wetCDOMdiff` | `fluorescenceDifference` | mg/m^3; WET Labs CDOM |
`wetChAbs` | `fluorescence` | 1/m; WET Labs AC3 absorption |
`wetStar~` | `fluorescence` | mg/m^3; WET Labs WETstar |
`wetStardiff` | `fluorescenceDifference` | mg/m^3; WET Labs WETstar |
`xmiss` | `beamTransmission` | percent; Chelsea/Seatech |
`xmiss~` | `beamTransmission` | percent; Chelsea/Seatech |

Notes:

1. 'pr' is in a Dalhousie-generated data file but seems not to be in reference 1.

2. this is an odd unit, and so if `sw*` functions are called on an object containing this, a conversion will be made before performing the computation. Be on the lookout for errors, since this is a rare situation.

3. assume ITS-90 temperature scale, since sample `.cnv` file headers do not specify it.

4. some files have PSU for this. Should we handle that? And are there other S scales to consider?

5. 'theta' may appear in different ways with different encoding configurations, set up within R or in the operating system.

### Value

a list containing `name` (the oce name), `nameOriginal` (the SBE name) and `unit`.

### Author(s)

Dan Kelley

### References

1. A SBE data processing manual was once at `http://www.seabird.com/document/sbe-data-processing-manual`, but as of summer 2018, this no longer seems to be provided by SeaBird. A web search will turn up copies of the manual that have been put online by various research groups and data-archiving agencies. As of 2018-07-05, the latest version was named `SBEDataProcessing_7.26.4.pdf` and had release date 12/08/2017, and this was the reference version used in coding `oce`.

### See Also

Other things related to ctd data: `CTD_BCD2014666_008_1_DN.ODF.gz`, `[[,ctd-method`, `[[<-,ctd-method`, `as.ctd()`, `ctd-class`, `ctd.cnv`, `ctdDecimate()`, `ctdFindProfiles()`, `ctdRaw`, `ctdTrim()`, `ctd`, `d200321-001.ctd`, `d201211_0011.cnv`, `handleFlags,ctd-method`, `initialize,ctd-method`, `initializeFlagScheme,ctd-method`, `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()`, `setFlags,ctd-method`, `subset,ctd-method`, `summary,ctd-method`, `woceNames2oceNames()`, `woceUnit2oceUnit()`, `write.ctd()`

Other functions that interpret variable names and units from headers: `ODFNames2oceNames()`, `oceNames2whpNames()`, `oceUnits2whpUnits()`, `unitFromStringRsk()`, `unitFromString()`, `woceNames2oceNames()`, `woceUnit2oceUnit()`

[Package oce version 1.2-0 Index]