read.ctd {oce} | R Documentation |
Read a CTD data file, producing an object of type ctd
.
read.ctd(file, type=NULL, columns=NULL, station=NULL, monitor=FALSE, debug=getOption("oceDebug"), processingLog, ...) read.ctd.sbe(file, columns=NULL, station=NULL, missing.value, monitor=FALSE, debug=getOption("oceDebug"), processingLog, ...) read.ctd.woce(file, columns=NULL, station=NULL, missing.value=-999, monitor=FALSE, debug=getOption("oceDebug"), processingLog, ...) read.ctd.woce.other(file, columns=NULL, station=NULL, missing.value=-999, monitor=FALSE, debug=getOption("oceDebug"), processingLog, ...) read.ctd.odf(file, columns=NULL, station=NULL, missing.value=-999, monitor=FALSE, debug=getOption("oceDebug"), processingLog, ...) read.ctd.odv(file, columns=NULL, station=NULL, missing.value=-999, monitor=FALSE, debug=getOption("oceDebug"), processingLog, ...) read.ctd.itp(file, columns=NULL, station=NULL, missing.value=-999, monitor=FALSE, debug=getOption("oceDebug"), processingLog, ...)
file |
a connection or a character string giving the name of the file to
load. For |
type |
if |
debug |
a flag that turns on debugging. Set to 1 to get a moderate amount of debugging information, or to 2 to get more. |
columns |
if |
station |
optional character string containing an identifying name (or number) for the station. (This can be useful if the routine cannot determine the name automatically, or if another name is preferred.) |
missing.value |
optional missing-value flag; data matching this value
will be set to |
monitor |
boolean, set to |
processingLog |
if provided, the action item to be stored in the log. (Typically only provided for internal calls; the default that it provides is better for normal calls by a user.) |
... |
additional arguments, passed to called routines. |
These functions read CTD datasets that have been stored in common
formats, and could be extended to accommodate other formats if needed. The
basic function is read.ctd
, which analyzes some of the file contents,
and then calls one of the following, any of which can be called directly.
read.ctd.sbe()
reads files files created by Seabird CTD
instruments. These are recognized by a first line with first ten characters
“* Sea-Bird
.”
read.ctd.woce()
reads files stored in the exchange format used
by the World Ocean Circulation Experiment (WOCE) (first 4 characters of the
first line being “CTD,
”), and also in a rarer format with the first
3 characters being “CTD
” followed by a blank or the end of the
line).
read.ctd.woce.other()
reads the format called “CTD” in the
section of the archive websites named “Other formats.” These data are
stored in filenames ending .WCT
, and they do not have a great deal of
metadata (e.g. longitude), so the user is forced to infer such things from a
separate file. Support for this data type is limited, e.g. requiring a
header of a certain length and data columns in a certain order.
Improvements are unlikely to be added to the function, since this data type
seems to offer no advantages over the type handled by
read.ctd.woce()
.
read.ctd.odf()
reads files stored in Ocean Data Format, used in
some Canadian hydrographic databases.
Different file types provide different meta-information. For example, the
WOCE exchange format binds together the institute name and the initials of
the chief scientist into a single string that read.ctd
cannot parse,
so both object@metadata$institute
and
object@metadata$scientist
are left blank for WOCE files.
An object of class
"ctd"
, which is a list with
elements detailed below. The most important elements are the station name and
position, along with the profile data that are contained in the data frame
named data
. (Other elements in the list may be deleted in future
versions of the package, if they prove to be of little use in practice, or if
they prove to have been idiosyncratic features of the particular files used in
early development of oce
.)
|
: a list containing the profile data. The column names are
discovered from the header, and may differ from file to file. For example,
some CTD instruments may have a fluorometer connected, others may not. The
order of the columns may vary from case to case, and so it is important to
refer to them by name. The following vectors are normally present:
|
|
: a list containing the following items
|
|
: a log of processing, in the standard |
The functions attempt to infer a wide range of meta-information
from file headers, but variations in these headers limit generality. For
example, read.ctd.sbe
handles water depths in any of the following
forms, but ostensibly similar forms may not work.
** DEPTH = 100 ** Water Depth: 40 m ** Depth (m): 3447 ** Depth: 16 ** Profondeur: 92
Similar issues come up for other items in CTD headers. For example, date
variants can cause a problem if, say, a date is stored in American notation
but the user is in another locale, where dates are represented differently;
a solution is to call Sys.setlocale("LC_TIME", "en_US")
before
reading the data.
Even when read.ctd
appears to have read the data without error, the
prudent user will do some plots and summaries on a sample file. It is also
a good idea to examine some inferred numerical values in comparison with the
information in the data file. CTD profiles are not cheap to acquire, and
publishing erroneous results is highly embarrassing. The rewards of having
confidence in the data surely outweigh the cost of a half hour spent looking
at the data.
Three sample files are provided with the package, in
system.file("extdata", "ctd.cnv", package="oce")
system.file("extdata", "d200321-001.ctd", package="oce")
system.file("extdata", "CTD_BCD2010666_01_01_DN.ODF", package="oce")
and an examination of these in relationship with the existing code should help users to understand the present implementation, providing insights on extending it for their own data.
Dan Kelley
The Sea-Bird SBE 19plus profiler is described at http://www.seabird.com/products/spec_sheets/19plusdata.htm. Some more information is given in the Sea-Bird data-processing manaual http://www.seabird.com/old-manuals/Software_Manuals/SBE_Data_Processing/SBEDataProcessing_7.20g.pdf.
The WOCE-exchange format is described at
http://woce.nodc.noaa.gov/woce_v3/wocedata_1/whp/exchange/exchange_format_desc.htm
,
and a sample file is at
http://woce.nodc.noaa.gov/woce_v3/wocedata_1/whp/exchange/example_ct1.csv
The ODF format, used by the Canadian Department of Fisheries and Oceans, is
described to some extent in the documentation for read.odf
. It
is not clear that ODF format is handled correctly in read.ctd.odf
, or
the more general function read.odf
, because the format seems to
be somewhat variable and some of the R code is designed mainly by examination
of some particular files being used in the author's research.
The ODV
format, used by the ODV software and some European/British data
providers, is described in a file stored on the website of the British
Oceanographic Data Center, bodc.ac.uk
, in a directory named
data/codes_and_formats/odv_format
. (The URL is not provided here
because it is unreliable, which causes problems with CRAN submission of the
oce package.)
Information about ice-tethered profile data is provided at http://www.whoi.edu/page.do?pid=23096, which also provides a link for downloading data. Note that the present version only handles data in profiler-mode, not fixed-depth mode.
The documentation for ctd-class
explains the structure of
ctd
objects, and also outlines the other functions dealing with them.
library(oce) ## Not run: ## Labrador Sea data, file 0001919.tar.gz from website ## http://www.nodc.noaa.gov/cgi-bin/OAS/prd/accession/download d <- read.ctd.woce("*.csv") data(coastlineWorld) plot(coastlineWorld, clat=55, clon=-50, span=5000) longitude <- sapply(d, function(stn) stn[['longitude']]) latitude <- sapply(d, function(stn) stn[['latitude']]) points(longitude, latitude, col='red') ## End(Not run)