as.ctd: Coerce Data Into a ctd Object

View source: R/ctd.R

as.ctdR Documentation

Coerce Data Into a ctd Object

Description

Assemble data into a ctd object. This function is complicated (spanning approximately 500 lines of code) because it tries to handle many special cases, and tries to make sensible defaults for unspecified parameters. If odd results are found, users might find it helpful to call this function with the first argument being a simple vector of Practical Salinity values, in which case the processing of the other arguments is relatively straightforward.

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 ^\circC 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.

latitude

optional numerical value containing the latitude in decimal degrees, positive in the northern hemisphere. See the note on length, for the longitude argument.

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.

Details

The following sections provide an some notes on how as.ctd() handles certain object types given as the first parameter.

Converting argo objects

If the salinity argument is an object of argo, then that object is dismantled and reassembled as a ctd object in ways that are mostly straightforward, although the handling of time depends on the information in the original netcdf data file that was used by read.argo() to create the argo object.

All Argo data files contain an item called juld from which the profile time can be computed, and some also contain an additional item named MTIME, from which the times of individual measurements can also be computed. Both cases are handled by as.ctd(), using a scheme outlined in Note 4 of the Details section of the read.argo() documentation.

Converting rsk objects

If the salinity argument is an object of rsk, then as.ctd passes it, pressureAtmospheric, longitude, latitude ship, cruise, station and deploymentType to rsk2ctd(), which builds the ctd object that is returned by as.ctd. The other arguments to as.ctd are ignored in this instance, because rsk objects already contain their information. If required, any data or metadata element can be added to the value returned by as.ctd using oceSetData() or oceSetMetadata(), respectively.

The returned rsk object contains pressure in a form that 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.

rsk objects may store sea pressure or absolute pressure (the sum of sea pressure and atmospheric pressure), depending on how the object was created with as.rsk() or read.rsk(). However, ctd objects store sea pressure, which is needed for plotting, calculating density, etc. This poses no difficulties, however, because as.ctd automatically converts absolute pressure to sea pressure, if the metadata in the rsk object indicates that this is appropriate. Further alteration of the pressure can be accomplished with the pressureAtmospheric argument, as noted above.

Value

A ctd object.

Author(s)

Dan Kelley

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.

See Also

Other things related to ctd data: CTD_BCD2014666_008_1_DN.ODF.gz, [[,ctd-method, [[<-,ctd-method, cnvName2oceName(), ctd, ctd-class, ctd.cnv.gz, ctdDecimate(), ctdFindProfiles(), ctdFindProfilesRBR(), ctdRaw, ctdRepair(), ctdTrim(), ctd_aml.csv.gz, d200321-001.ctd.gz, d201211_0011.cnv.gz, handleFlags,ctd-method, initialize,ctd-method, initializeFlagScheme,ctd-method, oceNames2whpNames(), oceUnits2whpUnits(), plot,ctd-method, plotProfile(), plotScan(), plotTS(), read.ctd(), read.ctd.aml(), read.ctd.itp(), read.ctd.odf(), read.ctd.odv(), read.ctd.saiv(), read.ctd.sbe(), read.ctd.ssda(), read.ctd.woce(), read.ctd.woce.other(), setFlags,ctd-method, subset,ctd-method, summary,ctd-method, woceNames2oceNames(), woceUnit2oceUnit(), write.ctd()

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)

# 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 = "")
    )
)


dankelley/oce documentation built on March 18, 2024, 2:02 p.m.