Coerce Data Into a ctd Object

Assemble data into a ctd object. There are two ways this can work. First, salinity can be a vector of numeric values, in which case the other parameters will be interpreted as described below. Second, salinity can be an oce object, in which case the action depends on the object class, as described in the ‘Details’.

Usage

as.ctd(
  salinity,
  temperature = NULL,
  pressure = NULL,
  conductivity = NULL,
  scan = NULL,
  time = NULL,
  units = NULL,
  flags = NULL,
  missingValue = NULL,
  type = "",
  serialNumber = NULL,
  ship = NULL,
  cruise = NULL,
  station = NULL,
  startTime = NULL,
  longitude = NULL,
  latitude = NULL,
  deploymentType = "unknown",
  pressureAtmospheric = 0,
  sampleInterval = NULL,
  profile = NULL,
  debug = getOption("oceDebug")
)

Arguments

salinity: may be (1) a numeric vector holding Practical Salinity, (2) a list or data frame holding salinity and other hydrographic variables or (3) an oce-class object that holds hydrographic information. If salinity is not provided, then conductivity must be provided, so that swSCTp() can be used to compute salinity.
temperature: a numeric vector containing in-situ temperature in \(^\circ\)C on the ITS-90 scale; see “Temperature units” in the documentation for swRho().
pressure: a numeric vector containing sea pressure values, in decibars. Typically, this vector has the same length as salinity and temperature, but it also possible to supply just one value, which will be repeated to get the right length. Note that as.ctd() stores the sum of pressure and pressureAtmospheric in the returned object, although the default value for pressureAtmospheric is zero, so in the default case, pressure is stored directly.
conductivity: an optional numeric vector containing electrical conductivity ratio through the water column. To convert from raw conductivity in milliSeimens per centimeter divide by 42.914 to get conductivity ratio (see Culkin and Smith, 1980).
scan: optional numeric vector holding scan number. If not provided, this is set to seq_along(salinity).
time: optional vector of times of observation.
units: an optional list containing units. If not supplied, defaults are set for pressure, temperature, salinity, and conductivity. Since these are simply guesses, users are advised strongly to supply units. See “Examples”.
flags: if supplied, this is a list containing data-quality flags. The elements of this list must have names that match the data provided to the object.
missingValue: optional missing value, indicating data that should be taken as NA. Set to NULL to turn off this feature.
type: optional type of CTD, e.g. "SBE"
serialNumber: optional serial number of instrument
ship: optional string containing the ship from which the observations were made.
cruise: optional string containing a cruise identifier.
station: optional string containing a station identifier.
startTime: optional indication of the start time for the profile, which is used in some several plotting functions. This is best given as a POSIXt time, but it may also be a character string that can be converted to a time with as.POSIXct(), using UTC as the timezone.
longitude: optional numerical value containing longitude in decimal degrees, positive in the eastern hemisphere. If this is a single number, then it is stored in the metadata slot of the returned value; if it is a vector of numbers, then they are stored in the data slot. If longitude' is not provided (i.e. if it is NULL, the default), then as.ctd()' tries to find it from the first parameter, if it is a list, or an oce object.
latitude: similar to longitude. Positive in the northern hemisphere.
deploymentType: character string indicating the type of deployment. Use "unknown" if this is not known, "profile" for a profile (in which the data were acquired during a downcast, while the device was lowered into the water column, perhaps also including an upcast; "moored" if the device is installed on a fixed mooring, "thermosalinograph" (or "tsg") if the device is mounted on a moving vessel, to record near-surface properties, or "towyo" if the device is repeatedly lowered and raised.
pressureAtmospheric: A numerical value (a constant or a vector), that is subtracted from pressure before storing it in the return value. (This altered pressure is also used in calculating salinity, if that is to be computed from conductivity, etc., using swSCTp(); see salinity above.)
sampleInterval: optional numerical value indicating the time between samples in the profile.
profile: optional positive integer specifying the number of the profile to extract from an object that has data in matrices, such as for some argo objects. Currently the profile argument is only utilized for argo objects.
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.

Value

A ctd object.

Details

If the first parameter, salinity, is an oce object, then the action depends on the class of that object.

If salinity is ctd object, then `as.ctd()1 returns a copy of it.
If salinity is an argo object, then as.ctd() calls argo2ctd() with that object as its first parameter, along with the value of profile and the value of debug minus 1. All other parameters provided to as.ctd() are ignored. Note that Argo notation is retained in the return value, so that e.g. there is no metadata item named station (instead, id and cycleNumber are defined), and no item named startTime (instead, time is defined. These name changes are understood by the summary() and plot() functions. Breaking Change: Until version 1.8-4, as.ctd() also processed the parameters that are ignored now. This behaviour was changed because many of those parameters (e.g. cruise and ship) make no sense for Argo data. Users should now use oceSetMetadata() to insert additional items as desired.
If salinity is an rsk object, then as.ctd() calls rsk2ctd() with that object as its first argument, along with pressureAtmospheric, longitude, latitude and debug minus 1, ignoring all the other parameters. Note that pressure in the returned object may need to be adjusted, because rsk objects may contain either absolute pressure or sea pressure. This adjustment is handled automatically by as.ctd, by examination of the metadata item named pressureType (described in the documentation for read.rsk()). Once the sea pressure is determined, adjustments may be made with the pressureAtmospheric argument, although in that case it is better considered a pressure adjustment than the atmospheric pressure.

References

Culkin, F., and Norman D. Smith, 1980. Determination of the concentration of potassium chloride solution having the same electrical conductivity, at 15 C and infinite frequency, as standard seawater of salinity 35.0000 ppt (Chlorinity 19.37394 ppt). IEEE Journal of Oceanic Engineering, volume 5, pages 22-23.

Author

Dan Kelley, with help from Clark Richards

Examples

library(oce)
# 1. fake data, with default units
pressure <- 1:50
temperature <- 10 - tanh((pressure - 20) / 5) + 0.02 * rnorm(50)
salinity <- 34 + 0.5 * tanh((pressure - 20) / 5) + 0.01 * rnorm(50)
ctd <- as.ctd(salinity, temperature, pressure)
# Add a new column
fluo <- 5 * exp(-pressure / 20)
ctd <- oceSetData(ctd,
    name = "fluorescence", value = fluo,
    unit = list(unit = expression(mg / m^3), scale = "")
)
summary(ctd)
#> CTD Summary
#> -----------
#> 
#> * Data Overview
#> 
#>                              Min.    Mean   Max.   Dim. NAs OriginalName
#>     scan                     1       25.5   50     50   0   "-"         
#>     salinity [PSS-78]        33.49   34.108 34.519 50   0   "-"         
#>     temperature [°C, ITS-90] 8.962   9.7833 11.033 50   0   "-"         
#>     pressure [dbar]          1       25.5   50     50   0   "-"         
#>     fluorescence [mg/m³]     0.41042 1.7903 4.7561 50   0   "-"         
#> 
#> * Processing Log
#> 
#>     - 2024-12-23 20:38:46 UTC: `create 'ctd' object`
#>     - 2024-12-23 20:38:46 UTC: `as.ctd(salinity = salinity, temperature = temperature, pressure = pressure)`
#>     - 2024-12-23 20:38:46 UTC: `oceSetData(object = ctd, name = "fluorescence", value = fluo,     unit = list(unit = expression(mg/m^3), scale = ""))`

# 2. fake data, with supplied units (which are the defaults, actually)
ctd <- as.ctd(salinity, temperature, pressure,
    units = list(
        salinity = list(unit = expression(), scale = "PSS-78"),
        temperature = list(unit = expression(degree * C), scale = "ITS-90"),
        pressure = list(unit = expression(dbar), scale = "")
    )
)