Introduction to the earthtide package

Code background

earthtide is a port of the ‘Fortran ETERNA 3.4’ (Wenzel, 1996) predict and part of the analyze codes with the Kudryavtsev 2004 update. The original Fortran code was rewritten in R, and C++ using the great Rcpp, RcppArmadillo, and RcppParallel. The package is useful for generating synthetic earth tides using highly accurate tidal catalogs for prediction and regression applications in R. Attempts were made to ensure that results were consistent with the ETERNA 3.4 results, however, it is possible that a bug was introduced during the conversion and update. For the most feature rich version and up-to-date version of ETERNA please see http://ggp.bkg.bund.de/eterna/ maintained by Klaus Schueller.

Hartmann, T., Wenzel, H.-G., 1995. The HW95 tidal potential catalogue. Geophys. Res. Lett. 22, 3553–3556. (https://doi.org/10.1029/95GL03324)

Kudryavtsev, S.M., 2004. Improved harmonic development of the Earth tide-generating potential. J. Geod. 77, 829–838. (https://doi.org/10.1007/s00190-003-0361-2)

Wenzel, H.G. 1996: The nanogal software: Earth tide data processing package ETERNA 3.30. Bull. Inf. Marges Terrestres. 124, 9425-9439. (http://www.eas.slu.edu/GGP/ETERNA34/MANUAL/ETERNA33.HTM)

Setup

The first step to generate earthtides is to create the object with the prediction times, station, catalog and frequency details. The following are the most commonly used parameters:

utc is a vector of POSIXct times for earth tide prediction. This should typically be a regular time series (equally spaced) as the method is most efficient for this case, however, irregular time series are also accepted.
latitude numeric of length one. The latitude of the monitoring location.
longitude numeric of length one. The longitude of the monitoring location.
cutoff numeric of length one. Cutoff determines how many waves to include in the analysis. A lower number yields more precise results but at the cost of runtime. A value of 1e-10 includes all waves in the catalog and may be quite slow for long series. The default is 1e-6.
wave_groups is a data.frame of of the frequency ranges in cycles per day. It requires a column named start and an column named end which give the ranges for each wave group.

See ?Earthtide for the complete list of available arguments.

library(earthtide)

# One month of hourly data
tms <- as.POSIXct("2015-01-01", tz = "UTC") + 0:(24*31) * 3600

et <- Earthtide$new(
  utc = tms,
  latitude = 52.3868,
  longitude = 9.7144,
  wave_groups = data.frame(start = 0.0, end = 6.0))

LOD (length of day) tide and pole tide

The Length of Day (LOD) and Pole tides are calculated in this initial step.

Predict

The predict method of the earthtide class computes the tidal response. There are two options for this function:

method determines the which response is desired. Currently valid options are “gravity”, “tidal_potential”, “tidal_tilt”, “vertical_displacement”, “vertical_strain”, “areal_strain”, “volume_strain”, and “ocean_tides”.
astro_update determines how often phases are updated. For long time series (greater than 100,000 times) a value greater than 1 can speed up the results. In general, values greater than 1 will only be necessary for predicting at the minute or second scale or if you are predicting for many years. There may be a slight loss of precision when the cutoff is small. For small cutoff values use a small value for astro_update and we suggest testing to achieve the desired precision.

et$predict(method = 'gravity', astro_update = 24)

Analyze

To generate normalized curves for use in regression equations we use the analyze method instead of the predict method. All other arguments remain the same. This will generate normalized sin and cos terms for each wavegroup. In the example we plot the first 5 of a 22 wave groups set. These may be used in your preferred analyses.

wave_groups <- na.omit(eterna_wavegroups[eterna_wavegroups$time == '1 month', 
                                        c('start', 'end')])

et <- Earthtide$new(utc = tms, 
                    latitude = 49.00937,
                    longitude = 8.40444,
                    elevation = 120,
                    cutoff = 1e-10,
                    catalog = 'hw95s',
                    wave_groups = wave_groups)

print(wave_groups[1:5,], row.names = FALSE)

##     start      end
##  0.020885 0.054747
##  0.054748 0.091348
##  0.091349 0.501369
##  0.501370 0.911390
##  0.911391 0.947991

et$analyze(method = 'gravity', astro_update = 1)

Get the tidal values

The tide method of the earthtide class computes returns a data.frame of tidal values. The following example in the chaining section shows how to calculate the gravity, LOD (length of day), and pole tides and return a data.frame of the values.

Chaining

It is also possible to chain operations together for more compact code.

tides <- Earthtide$
  new(utc = as.POSIXct("2015-01-01", tz = "UTC") + 0:(24*31) * 3600,
      latitude = 52.3868,
      longitude = 9.7144,
      wave_groups = data.frame(start = 0.0, end = 6.0))$
  predict(method = "gravity", astro_update = 1)$
  lod_tide()$
  pole_tide()$
  tide()
  

print(tides[1:5,], row.names = FALSE)

##             datetime    gravity  lod_tide pole_tide
##  2015-01-01 00:00:00 -161.41752 0.3261749 -3.158627
##  2015-01-01 01:00:00   89.96493 0.3243483 -3.169631
##  2015-01-01 02:00:00  321.51996 0.3225816 -3.180498
##  2015-01-01 03:00:00  500.73006 0.3208721 -3.191230
##  2015-01-01 04:00:00  610.79496 0.3192170 -3.201824