read.ctd.aml() reads files that hold data acquired with an AML Oceanographic BaseX2 CTD instrument. The SeaCast software associated with this device can output data in several formats, of which only two are handled, and only one is recommended (see ‘Details’).

read.ctd.aml(
  file,
  format,
  encoding = "UTF-8-BOM",
  debug = getOption("oceDebug"),
  processingLog,
  ...
)

Arguments

file

a connection or a character string giving the name of the file to load.

format

an integer indicating the format type. If not supplied, the first line is examined to determine whether the file matches the format=1 or format=2 style (see ‘Details’).

encoding

a character value that indicates the encoding to be used for this data file, if it is textual. The default value for most functions is "latin1", which seems to be suitable for files containing text written in English and French.

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.

processingLog

ignored.

...

ignored.

Value

read.ctd.aml() returns a ctd object.

Details

The handled formats match files available to the author, both of which diverge slightly from the format described in the AML documentation (see “References”).

Regardless of the format, files must contain columns named Conductivity (mS/cm), Temperature (C) and Pressure (dBar), because ctd objects need those quantities. (Actually, if pressure is not found, but Depth (m) is, then pressure is estimated with swDepth(), as a workaround.) Note that other columns will be also read and stored in the returned value, but they will not have proper units. Attempts are made to infer the sampling location from the file, by searching for strings like Latitude= in the header. Headers typically contain two values of the location, and it is the second pair that is used by this function, with a NA value being recorded if the value in the file is no-lock. The instrument serial number is also read, although the individual serial numbers of the sensors are not read. Position and serial number are stored in the the metadata slot of the returned value. The entire header is also stored there, to let users glean more about dataset.

Two formats are handled, as described below. Format 1 is greatly preferred, because it is more robust (see below on format=2) and also because it can be read later by the AML SeaCast software.

  1. If format is 1 then the file is assumed to be in a format created by selecting Export As ... Seacast (.csv) in AML's SeaCast software, with settings to output pressure (or, as second-best, depth), temperature and conductivity, and perhaps other things. The delimiter must be comma. If date and time are output, their formats must be yyyy-mm-dd and UTC, respectively. Decoding the file proceeds as follows. First, a check is done to ensure that the first line consists of the string [cast header]. Then an attempt is made to infer location and serial number from the header. After this, read.ctd.aml() searches down for a line containing the string [data]. The first line thereafter is taken as a comma-separated list of variable names, and lines following that are taken to hold the variable values, separated by commas.

  2. If format is 2 then the first line must be a comma-separated list of column names. This may be followed by header information, which is handled similarly as for format=1. The data are read from all lines that have the same number of commas as the first line, an admittedly brittle strategy developed as a way to handle some files that lacked other information about the end of the header.

In both cases, the data columns, renamed to oce convention, are stored in the data slot. For the mandatory variables, units are also stored, as for other ctd objects.

References

AML Oceanographic. "SeaCast 4 User Manual (Version 2.06)." AML Oceanographic, Mahy 2016. https://www.subseatechnologies.com/media/files/page/032e50ac/seacast-4-2-user-manual-sti.pdf.

Author

Dan Kelley

Examples

library(oce)
f <- system.file("extdata", "ctd_aml.csv", package="oce")
d <- read.ctd.aml(f)
summary(d)
#> CTD Summary
#> -----------
#> 
#> * File:                "/private/var/folders/8b/l4h64m1j22v5pb7vj049ff140000gn/T/RtmpMVjKWh/temp_libpath54107b4abcb3/oce/extdata/ctd_aml.csv"
#> * Location:            70.228N 145.85W
#> * Time ranges from 2021-07-25 18:22:28 to 2021-07-25 18:22:30 with 50 samples and mean increment 0.04020408 s
#> * Data Overview
#> 
#>                                Min.   Mean   Max. Dim. NAs         OriginalName
#>     scan                          1   25.5     50   50   0                    -
#>     salinity [PSS-78]        5.5779 26.323 28.503   50   0                    -
#>     temperature [°C, ITS-90]  3.414 4.8729  5.671   50   0      Temperature (C)
#>     pressure [dbar]            0.22 0.8592   1.69   50   0                    -
#>     conductivity [mS/cm]      6.281 25.687 27.139   50   0 Conductivity (mS/cm)
#>     Date                         NA     NA     NA   50   0                 Date
#>     Time                         NA     NA     NA   50   0                 Time
#>     battery [V]                7.93   7.93   7.93   50   0          Battery (V)
#> 
#> * Processing Log
#> 
#>     - 2022-08-18 15:46:55 UTC: `create 'ctd' object`
#>     - 2022-08-18 15:46:55 UTC: `as.ctd(salinity = S, temperature = data$temperature, pressure = data$pressure,     conductivity = data$conductivity, serialNumber = serialNumber,     longitude = longitude, latitude = latitude, debug = debug -         1L)`
#>     - 2022-08-18 15:46:55 UTC: `read.ctd.aml(file = f)`