% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sealevel.R
\name{read.sealevel}
\alias{read.sealevel}
\title{Read a sealevel File}
\usage{
read.sealevel(
  file,
  tz = getOption("oceTz"),
  encoding = "latin1",
  processingLog,
  debug = getOption("oceDebug")
)
}
\arguments{
\item{file}{either of three choices: (1) a connection, (2)
a character vector of length 1, giving the name of the file
to load (see \sQuote{Details} for the possible file formats)
or (3) a character vector of length 2 giving the
names of 2 files that are to be passed, along with \code{debug} (but
no other arguments) to \link{read.sealevel.gc2026}.}

\item{tz}{time zone.  The default value, \code{oceTz}, is set to \code{UTC}
at setup.  (If a time zone is present in the file header, this will
supercede the value given here.)}

\item{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
\code{"latin1"}, which seems to be suitable for files containing text written in
English and French.}

\item{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.)}

\item{debug}{an integer specifying whether debugging information is
to be printed during the processing. This is a general parameter that
is used by many \code{oce} functions. Generally, setting \code{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
\code{debug} first, so that a user can often obtain deeper debugging
by specifying higher \code{debug} values.}
}
\value{
A \linkS4class{sealevel} object.
}
\description{
Read a data file holding sea level data.  BUG: the time vector assumes GMT,
regardless of the GMT.offset value.
}
\details{
This function starts by scanning the first line of the file, from which it
determines whether the file is in one of two known formats: type 1, the
format used at the Hawaii archive centre, and type 2, the
comma-separated-value format used by the Marine Environmental Data Service.
The file type is inferred by examination of its first line. If that contains
the string \code{Station_Name} the file is of type 2. If
the file is in neither of these formats, the user might wish to scan it
directly, and then to use \code{\link[=as.sealevel]{as.sealevel()}} to create a
\code{sealevel} object.

The Hawaii archive site at
\verb{http://ilikai.soest.hawaii.edu/uhslc/datai.html} at one time provided a graphical
interface for downloading sealevel data in Type 1, with format that was once
described at \verb{http://ilikai.soest.hawaii.edu/rqds/hourly.fmt} (although that link
was observed to no longer work, on December 4, 2016).
Examination of data retrieved from what seems to be a replacement Hawaii server
(https://uhslc.soest.hawaii.edu/data/?rq) in September 2019 indicated that the
format had been changed to what is called Type 3 by \code{read.sealevel}.
Web searches did not uncover documentation on this format, so the
decoding scheme was developed solely through examination of
data files, which means that it might be not be correct.
The MEDS repository (\code{http://www.isdm-gdsi.gc.ca/isdm-gdsi/index-eng.html})
provides Type 2 data.
}
\seealso{
Other things related to sealevel data: 
\code{\link{[[,sealevel-method}},
\code{\link{[[<-,sealevel-method}},
\code{\link{as.sealevel}()},
\code{\link{plot,sealevel-method}},
\code{\link{read.sealevel.gc2026}()},
\code{\link{sealevel}},
\code{\link{sealevel-class}},
\code{\link{sealevelTuktoyaktuk}},
\code{\link{subset,sealevel-method}},
\code{\link{summary,sealevel-method}}
}
\author{
Dan Kelley
}
\concept{things related to sealevel data}
