oce (version 0.2-1)

tidem: Fit a tidal model to a timeseries

Description

Fit a tidal model to a timeseries.

Usage

tidem(sl, constituents, latitude=NULL, startTime, rc=1, quiet=TRUE)

Arguments

sl

a sealevel object, or a list of numbers indicating sealevel.

constituents

an optional list of tidal constituents to which the fit is done (see Details.)

latitude

if provided, the latitude of the observations. If not provided, tidem will try to infer this from sl.

startTime

optional the start time for the series. If not provided, this is taken as the first time of the first sample, which is inferred as 0 for the case where sl is a simple list, and inferred as the time of the first sample, if sl

rc

the value of the coefficient in the Rayleigh criterion.

quiet

set to FALSE to get extra information on the processing.

Value

• An object of class "tide", consisting of
• const
  constituent number, e.g. 1 for Z0, 1 for SA, etc.
• model
  the regression model
• name
  a vector of constituent names, in non-subscript format, e.g. "M2".
• frequency
  a vector of constituent frequencies, in inverse hours.
• amplitude
  a vector of fitted constituent amplitudes, in metres.
• phase
  a vector of fitted constituent phase. NOTE: The definition of phase is likely to change as this function evolves. For now, it is phase with respect to the first data sample.
• p
  a vector containing a sort of p value for each constituent. This is calculated as the average of the p values for the sine() and cosine() portions used in fitting; whether it makes any sense is an open question.

Bugs

1. 1.

{This function is not fully developed yet, and both the form of the call and the results of the calculation may change.} 2.{Nodal correction is not done.} 3.{The reported p value may make no sense at all, and it might be removed in a future version of this function. Perhaps a significance level should be presented, as in the software developed by both Foreman and Pawlowicz.} 4.{The phase is wrong, at least judging by the Foreman test data set. (For M2, this gives -98.838841 but Foreman gives 77.70.)}

Test with <code>data(sealevelTuktoyaktuk)</code>

Note: this is only a preliminary test, since tidem does not yet do nodal corrections, and also since the test dos not add the P1 and K2 constituents, as in the Foreman and T_TIDE cases. FIXME: delete this note when the code is finished.

The Foreman package produces M2 amplitude 0.4904m and phase 77.70 (Appendix 7.3), when P1 and K2 are added to the standard constituents. Under what one may assume are the same conditions, the demonstration within T_TIDE gives 0.4904m $\pm$ 0.037m and phase 77.70 $\pm$ 3.94.

Under the same conditions, the test given below results in amplitude 0.50072m and phase 143.1. data(sealevelTuktoyaktuk) tide <- tidem(sealevelTuktoyaktuk) summary(tide)

concept

tide

Details

The fit is done in terms of sine and cosine components at the indicated tidal frequencies, with the amplitude and phase being calculated from the resultant coefficients on the sine and cosine terms. The tidal constituents to be used in the analysis are specified as follows.

1. Case 1.

{If constituents is not provided, then the constituent list will be made up of the 69 constituents regarded by Foreman as standard. These include astronomical frequencies and some shallow-water frequencies, and are as follows: c("Z0", "SA", "SSA", "MSM", "MM", "MSF", "MF", "ALP1", "2Q1", "SIG1", "Q1", "RHO1", "O1", "TAU1", "BET1", "NO1", "CHI1", "PI1", "P1", "S1", "K1", "PSI1", "PHI1", "THE1", "J1", "SO1", "OO1", "UPS1", "OQ2", "EPS2", "2N2", "MU2", "N2", "NU2", "GAM2", "H1", "M2", "H2", "MKS2", "LDA2", "L2", "T2", "S2", "R2", "K2", "MSN2", "ETA2", "MO3", "M3", "SO3", "MK3", "SK3", "MN4", "M4", "SN4", "MS4", "MK4", "S4", "SK4", "2MK5", "2SK5", "2MN6", "M6", "2MS6", "2MK6", "2SM6", "MSK6", "3MK7", "M8").}

Case 2.{If the first item in constituents is the string "standard", then a provisional list is set up as in Case 1, and then the (optional) rest of the elements of constituents are examined, in order. Each of these constituents is based on the name of a tidal constituent in the Foreman (1977) notation. (To get the list, execute data(tide.constituents) and then execute cat(tide.constituents$name).) Each named constituent is added to the existing list, if it is not already there. But, if the constituent is preceeded by a minus sign, then it is removed from the list (if it is already there). Thus, for example, constituents=c("standard", "-M2", "ST32") would remove the M2 constituent and add the ST32 constituent.}

Case 3.{If the first item is not "standard", then the list of constituents is processed as in Case 2, but without starting with the standard list. As an example, constituents=c("K1", "M2") would fit for just the K1 and M2 components. (It would be strange to use a minus sign to remove items from the list, but the function allows that.)}

In each of the above cases, the list is reordered in frequency prior to the analysis, so that the results of summary.tidem will be in a familiar form.

Once the constituent list is determined, tidem prunes the elements of the list by using the Rayleigh criterion, according to which two constituents of frequencies $f_1$ and $f_2$ cannot be resolved unless the time series spans a time interval of at least $rc/(f_1-f_2)$. The value rc=1 yields nominal resolution.

A list of constituent names is created by the following: data(tidedata) print(tidedata$const$name)

The text should include discussion of the (not yet performed) nodal correction treatement.

References

Foreman, M. G. G., 1977. Manual for tidal heights analysis and prediction. Pacific Marine Science Report 77-10, Institute of Ocean Sciences, Patricia Bay, Sidney, BC, 58pp. Foreman, M. G. G., Neufeld, E. T., 1991. Harmonic tidal analyses of long time series. International Hydrographic Review, 68 (1), 95-108. Pawlowicz, Rich, Bob Beardsley, and Steve Lentz, 2002. Classical tidal harmonic analysis including error estimates in MATLAB using T_TIDE. Computers and Geosciences, 28, 929-937.

See Also

summary.tidem summarizes a "tide" object, plot.tidem plots one, and predict.tidem makes predictions from one. As for the input, sealevel objects may be created with as.sealevel or read.sealevel. See notes at sealevelTuktoyaktuk, which is test data set.

Examples

library(oce)
# Fake a week simple hourly data series (not sealevel object)
hour <- seq(0, 24 * 7)
# M2 tide with phase 45 degrees
eta <- 1 + 2 * sin(2 * pi * hour / 12.4206 + pi/4)
tide <- tidem(eta)
summary(tide)
# Check: only Z0 and M2 are significant
plot(tide)

# Supply a start time, using a sealevel object
t <- seq(0, 10*86400, 3600)		# 10 days
eta <- sin(0.080511401 * t * 2 * pi / 3600)
sl <- as.sealevel(eta,t+as.POSIXct("2009-02-13 00:00:00", tz="GMT"))
m <- tidem(sl, startTime=as.POSIXct("2009-02-13 00:00:00", tz="GMT"))
# Check: only M2 has non-negligible amplitude
summary(m)

# The demonstration time series from Foreman (1977),
# also used in T_TIDE (Pawlowicz, 2002).
data(sealevelTuktoyaktuk)
tide <- tidem(sealevelTuktoyaktuk)
summary(tide)