tidem: Fit a Tidem (Tidal Model) to a Timeseries

Description Usage Arguments Details Value Bugs Constituent Naming Convention Agreement with T_TIDE results Author(s) References See Also Examples

View source: R/tides.R

Description

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.

Usage

1
2
tidem(t, x, constituents, infer = NULL, latitude = NULL, rc = 1,
  regress = lm, debug = getOption("oceDebug"))

Arguments

t

Either a sealevel object (e.g. produced by read.sealevel or as.sealevel) or a vector of times. In the former case, time is part of the object, so t may not be given here. In the latter case, tidem needs a way to determine time, so t must be given.

x

an optional numerical vector holding something that varies with time. This is ignored if t is a sealevel-class object, in which case it is inferred as t[["elevation"]].

constituents

an optional vector of strings that name tidal constituents to which the fit is done (see “Details” and “Constituent Naming Convention”.)

infer

a list of constituents to be inferred from fitted constituents according to the method outlined in Section 2.3.4 of Foreman (1977) [1]. If infer is NULL, the default, then no such inferences are made. Otherwise, some constituents are computed based on other constituents, instead of being determined by regression at the proper frequency. If provided, infer must be a list containing four elements: name, a vector of strings naming the constituents to be inferred; from, a vector of strings naming the fitted constituents used as the sources for those inferences (these source constituents are added to the regression list, if they are not already there); amp, a numerical vector of factors to be applied to the source amplitudes; and phase, a numerical vector of angles, in degrees, to be subtracted from the source phases. For example, Following Foreman (1997) [1], if any of the name items have already been computed, then the suggested inference is ignored, and the already-computed values are used.

infer=list(name=c("P1","K2"),
           from=c("K1", "S2"),
           amp=c(0.33093, 0.27215),
           phase=c(-7.07, -22.4)

means that the amplitude of P1 will be set as 0.33093 times the calculated amplitude of K1, and that the P1 phase will be set to the K1 phase, minus an offset of -7.07 degrees. (This example is used in the Foreman (1977) [1] discussion of a Fortran analysis code and also in Pawlowicz et al. (2002) [4] discussion of the T_TIDE Matlab code. Rounded to the 0.1mm resolution of values reported in [1] and [2], the tidem results have root-mean-square amplitude difference to Foreman's Appendix 7.3 of 0.06mm; by comparison, the results in Table 1 of Pawlowicz et al. (2002) agree with Foreman's results to RMS difference 0.04mm.)

latitude

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

rc

the value of the coefficient in the Rayleigh criterion.

regress

function to be used for regression, by default lm, but could be for example rlm from the MASS package.

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.

Details

The tidal constituents to be used in the analysis are specified as follows; see “Constituent Naming Convention”.

In each of the above cases, the list is reordered in frequency prior to the analysis, so that the results of summary,tidem-method 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 f1 and f2 cannot be resolved unless the time series spans a time interval of at least rc/(f1-f2).

Finally, tidem looks in the remaining constituent list to check that the application of the Rayleigh criterion has not removed any of the constituents specified directly in the constituents argument. If any are found to have been removed, then they are added back. This last step was added on 2017-12-27, to make tidem behave the same way as the Foreman (1977) code [1], as illustrated in his Appendices 7.2 and 7.3. (As an aside, his Appendix 7.3 has some errors, e.g. the frequency for the 2SK5 constituent is listed there (p58) as 0.20844743, but it is listed as 0.2084474129 in his Appendix 7.1 (p41). For this reason, the frequency comparison is relaxed to a tol value of 1e-7 in a portion of the oce test suite (see tests/testthat/test_tidem.R in the source).

A specific example may be of help in understanding the removal of unresolvable constitutents. For example, the data(sealevel) dataset is of length 6718 hours, and this is too short to resolve the full list of constituents, with the conventional (and, really, necessary) limit of rc=1. From Table 1 of [1], this timeseries is too short to resolve the SA constituent, so that SA will not be in the resultant. Similarly, Table 2 of [1] dictates the removal of PI1, S1 and PSI1 from the list. And, finally, Table 3 of [1] dictates the removal of H1, H2, T2 and R2. Also, since Table 3 of [1] indicates that GAM2 gets subsumed into H1, and if H1 is already being deleted in this test case, then GAM2 will also be deleted.

A list of constituent names is created by the following:

1
2

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

Value

An object of tidem-class, 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. 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.

Constituent Naming Convention

tidem uses constituent names that follow the convention set by Foreman (1977) [1]. This convention is slightly different from that used in the T-TIDE package of Pawlowicz et al. (2002) [4], with Foreman's UPS1 and M8 becoming UPSI and MS in T-TIDE. As a convenience, tidem converts from these T-TIDE names to the Foreman names, issuing warnings when doing so.

Agreement with T_TIDE results

The tidem amplitude and phase results, obtained with

1
2
3
4
5
tidem(sealevelTuktoyaktuk, constituents=c("standard", "M10"),
     infer=list(name=c("P1", "K2"),
                from=c("K1", "S2"),
                amp=c(0.33093, 0.27215),
                phase=c(-7.07, -22.40))),

are identical the T_TIDE values listed in Table 1 of Pawlowicz et al. (2002), after rounding amplitude and phase to 4 and 2 digits past the decimal place, to match the format of the table.

Author(s)

Dan Kelley

References

1. 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.

2. Foreman, M. G. G., Neufeld, E. T., 1991. Harmonic tidal analyses of long time series. International Hydrographic Review, 68 (1), 95-108.

3. Leffler, K. E. and D. A. Jay, 2009. Enhancing tidal harmonic analysis: Robust (hybrid) solutions. Continental Shelf Research, 29(1):78-88.

4. 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

Other things related to tidem data: [[,tidem-method, [[<-,tidem-method, plot,tidem-method, predict.tidem, summary,tidem-method, tidedata, tidem-class, tidemAstron, tidemVuf

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
library(oce)
# The demonstration time series from Foreman (1977),
# also used in T_TIDE (Pawlowicz, 2002).
data(sealevelTuktoyaktuk)
tide <- tidem(sealevelTuktoyaktuk)
summary(tide)

# AIC analysis
extractAIC(tide[["model"]])

# Fake data at M2
t <- seq(0, 10*86400, 3600)
eta <- sin(0.080511401 * t * 2 * pi / 3600)
sl <- as.sealevel(eta)
m <- tidem(sl)
summary(m)

oce documentation built on Oct. 4, 2018, 5:04 p.m.