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, ... )
a connection or a character string giving the name of the file to load.
an integer indicating the format type. If not supplied, the
first line is examined to determine whether the file matches the
format=2 style (see ‘Details’).
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.
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
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
read.ctd.aml() returns a ctd object.
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
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
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
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 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
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 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.
AML Oceanographic. "SeaCast 4 User Manual (Version 2.06)." AML Oceanographic,
Other things related to ctd data:
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)`